Dokumentácia

Dokumentácia obsahuje widget 1.2.0, CMS pluginy 1.1.0 a API verziu 1.2.0. Posledná aktualizácia: júl 2026.

Rýchly štart

CallFlow je bezplatná miniaplikácia spätného volania s automatickým radením hovorov. Návštevník vašej webovej stránky zanechá telefónne číslo a požiadavka okamžite prejde do aplikácie CallFlow vo vašom telefóne. Spustenie trvá niekoľko minút a pozostáva z troch krokov:

1. Vytvorte si účet – v aplikácii CallFlow pre Android alebo novší webový panel. Účet je bezplatný.
2. Pridať stránku – V sekcii „Balíky a stránky“ pridajte adresu svojej webovej lokality a skopírujte krátky kľúč začínajúci 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. Prilepte skript - Umiestnite nasledujúci kód bezprostredne pred 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 webovej stránke sa zobrazí plávajúce tlačidlo a každá správa spustí upozornenie v aplikácii.

miniaplikácia HTML/JS

CallFlow 1.2.0 je produkčný skript pre bežné HTML stránky. Nevyžaduje rámec ani externé knižnice. Formulár beží v izolovanom Shadow DOM – nezasahuje do CSS vášho webu – a môže posielať nové požiadavky iba cez verejné CallFlow API.

Základná inštalácia (plávajúci widget)

Prilepte skript predtým </body> — dokładnie tak jak w Rýchly štart. Predvolený variant floating wyświetla pływający przycisk w rogu ekranu, który otwiera formularz.

Vložený variant v obsahu

Ak chcete formulár umiestniť na konkrétne miesto na stránke (napr. na podstránku kontaktu), pridajte prázdny kontajner a označte ho atribútom 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šetky varianty môžete sledovať naživo na webovej stránke Ukážka miniaplikácie.

Úplná tabuľka konfiguračných atribútov

Nastavenia naliehavosti a ochrany osobných údajov sa dodatočne získavajú z CallFlow. Používateľ webovej stránky nemôže povoliť funkciu, ktorú zakázal vlastník účtu.

Bezpečnosť a ochrana osobných údajov

• nečíta údaje účtu alebo zoznam tiketov;
• vám umožňuje iba vytvoriť lístok;
• prenos prebieha cez HTTPS;
• formulár obsahuje honeypot a vyžaduje výslovný súhlas na kontaktovanie;
• widget neukladá súbory cookie a nepoužíva miestne úložisko;
• číslo je normalizované a opätovne overené pomocou API;
• má časový limit 15 sekúnd a kľúč idempotencie na ochranu pred duplikátmi.

Prispôsobenie vzhľadu

Od verzie 1.2.0 miniaplikácia štandardne dedí písmo z webovej lokality (inherit, awaryjnie system-ui), a wygląd można dopasować na dwóch poziomach: Jednoduché (jednoduché atribúty) i Pokročilé (celospektrálne CSS). Na štítok je možné umiestniť atribúty prispôsobenia <script> alebo na cieli určenom používateľom data-target (atrybut na elemencie docelowym ma pierwszeństwo). Bez tych atrybutów widget wygląda tak jak dotychczas.

Jednoduchá úroveň - farby, rozmery, písmo

Každý atribút je voliteľný a mapuje sa na sadu premenných CSS na hostiteľskom prvku widgetu (.callflow-widget-host):

Príklad priradenia miniaplikácie k temnej strane so zlatými akcentmi:

<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>

Rovnaké premenné prenikajú do Shadow DOM prostredníctvom dedičnosti CSS, takže namiesto atribútov môžete použiť čistý CSS stránky (hárok alebo <style>):

#moj-kontener {

  --callflow-accent: #b8860b;

  --callflow-radius: 4px;

  --callflow-max-width: 460px;

}

Poradie priority: atribút 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ára majú atribúty 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 štýloch (kaskáda víťazí, ovplyvňuje interné selektory widgetov):

<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čítaného do Shadow DOM. Z bezpečnostných dôvodov sú akceptované iba 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>

Poradie štýlu Shadow DOM: základné štýly → list z data-css-href → data-custom-css. Personalizacja jest w pełni opcjonalna i wstecznie kompatybilna — istniejące osadzenia działają bez zmian.

JavaScript udalosti

Widget vysiela udalosti na hostiteľskom prvku a prenáša ich do dokumentu, takže môžete napríklad odoslať konverziu do analytického systému po úspešnej správe:

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

  console.log(event.detail.receiptId);

});



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

  console.warn(event.detail.code);

});

Dostupné udalosti:

• 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).

doplnok WordPress

CallFlow 1.1.0 pridá miniaplikáciu na celý váš web WordPress bez úpravy šablóny. Podporuje varianty floating, box, sticky i compact oraz osadzanie formularza w treści przez shortcode.

Požiadavky

• WordPress 6.0 alebo novší;
• PHP 7.4 alebo novší (testované na PHP 7.4 a 8.3);
• kľúč lokality Kľúč lokality CF-… utworzony w aplikacji CallFlow.

Inštalácia krok za krokom

1. Stiahnite si doplnok - súbor callflow-wordpress-1.1.0.zip znajdziesz w sekcji Stiahnuť.
2. Nainštalujte do hlavného panela WordPress - prejdite na Pluginy → Pridať nový plugin → Nahrať plugin na server, ukážte na stiahnutý súbor ZIP a kliknite Inštalovaťa po inštalácii Povoliť.
3. Konfigurovať - prejdite na Nastavenia → CallFlow a:
   • vložte kľúč do poľa PUBLIC_SITE_KEY (formát CF-XXXX-XXXX);
   • vyberte Vyžaduje sa Variant (predvolené floating);
   • zadajte adresu Zásady ochrany osobných údajov vašej stránky;
   • Globálne povoliť miniaplikáciu a kliknite Uložiť zmeny.

Vkladanie do obsahu (skrátený kód)

Ak chcete zobraziť formulár v príspevku alebo na stránke, použite krátky kód:

[callflow variant="box"]

Použitie krátkeho kódu automaticky deaktivuje druhú, globálnu miniaplikáciu na tejto podstránke – formulár nebude nikdy duplikovaný.

Bežné problémy

• Kľúč sa neukladá - Plugin overuje formát: kľúč musí začínať CF- i zawierać wyłącznie wielkie litery, cyfry i myślniki. Skopiuj go ponownie z aplikacji, bez spacji.
• Miniaplikácia sa na stránke nezobrazuje - kontrolné pole Globálne povoliť miniaplikáciu je skontrolovaný a kľúč nie je prázdny. Ak používate doplnok vyrovnávacej pamäte (napr. LiteSpeed, WP Super Cache), po uložení nastavení vymažte vyrovnávaciu pamäť.
• Miniaplikácia sa zobrazí dvakrát - máte aktívny aj doplnok CallFlow for WooCommerce; pozri časť WooCommerce.

doplnok WooCommerce

CallFlow pre WooCommerce 1.1.0 je doplnok prispôsobený pre obchody – používa variant 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žiadavky

• WordPress 6.0 alebo novší, PHP 7.4 alebo novší (testované na PHP 7.4 a 8.3);
• aktívny doplnok WooCommerce (povinné - bez neho sa widget nezobrazí);
• kľúč lokality Kľúč lokality CF-… z aplikacji CallFlow.

Inštalácia krok za krokom

1. Stiahnite si doplnok - súbor callflow-woocommerce-1.1.0.zip z sekcji Stiahnuť.
2. Inštalovať — Pluginy → Pridať nový plugin → Nahrať plugin na server, vyberte ZIP, Inštalovať, Povoliť.
3. Konfigurovať - prejdite na Nastavenia → CallFlow WooCommerce a:
   • vložiť PUBLIC_SITE_KEY;
   • vyberte Vyžaduje sa Variant: ecommerce (domyślny), floating lub sticky;
   • nastavte si svoj vlastný Hlavička formulár (predvolené "Máte otázku k produktu?");
   • Povoliť miniaplikáciu obchodu a uložte.

Funguje so základným doplnkom CallFlow

Oba doplnky môžu byť aktívne súčasne. Keď je povolená miniaplikácia WooCommerce, automaticky sa deaktivuje globálna miniaplikácia základného doplnku, takže formulár sa nikdy nezobrazí dvakrát. Ak necháte pole kľúča v nastaveniach WooCommerce prázdne, doplnok použije kľúč zo základného doplnku CallFlow.

Bežné problémy

• Miniaplikácia sa nezobrazí - uistite sa, že WooCommerce je nainštalovaný a aktívny; plugin zobrazuje widget iba vtedy, keď je spustený WooCommerce.
• Dve miniaplikácie naraz - aktualizujte oba pluginy na verziu 1.1.0; staršie verzie nekoordinovali viditeľnosť. Prípadne zrušte začiarknutie políčka „Povoliť widget globálne“ v základnom doplnku.
• Toto je beta - najskôr otestujte doplnok na pracovnej kópii obchodu a až potom ho povolte v produkcii.

Modul PrestaShop 8

Beta modul CallFlow 1.1.0 vkladá produkčný widget do päty obchodu PrestaShop (háčik displayFooter). Obsługuje warianty ecommerce, floating i sticky.

Požiadavky

• PrestaShop 8.0 alebo novší;
• kľúč lokality Kľúč lokality CF-… z aplikacji CallFlow;
• najskôr nainštalujte beta verziu do skúšobného obchodu.

Inštalácia krok za krokom

1. Stiahnuť modul - súbor callflow-prestashop8-1.1.0.zip z sekcji Stiahnuť.
2. Inštalovať na panel - prejdite na Moduly → Správca modulov → Načítať modul a ukážte na stiahnutý súbor ZIP. Modul nájdete v kategórii „Reklama a marketing“.
3. Konfigurovať - kliknite Konfigurovať pre modul CallFlow a:
   • vložiť PUBLIC_SITE_KEY;
   • vyberte Vyžaduje sa Variant: Elektronický obchod (predvolené), pohyblivé alebo rýchle;
   • súbor Hlavička miniaplikácie (predvolené "Máte otázku k tomuto produktu?" - zadajte vlastnú v poľštine);
   • uveďte adresa zásad ochrany osobných údajov obchod; Skript
   • nastavte prepínač Povolené na "Áno" a kliknite Uložiť.

Bežné problémy

• Chyba "Kľúč CallFlow musí začínať CF-" - modul overí formát kľúča; skopírujte ho z aplikácie bez medzier.
• Widget sa po uložení nezobrazí - vymazať vyrovnávaciu pamäť obchodu (Rozšírené → Výkon → Vymazať vyrovnávaciu pamäť) a skontrolujte, či je prepínač Enabled nastavený na "Yes".
• Téma nevyvoláva pätu - widget je pripojený k háku displayFooter; jeśli Twój motyw go nie renderuje, podepnij moduł do innego hooka w Vzhľad → Položky.

Iné platformy

Nasledujúce integrácie sú technickými beta verziami 1.1.0 – najskôr si ich nainštalujte do svojho pracovného prostredia. Všetky balíčky nájdete v sekcii Stiahnuť.

Drupal 10/11

Po nainštalovaní modulu prejdite na Konfigurácia → Sieťové služby → CallFlow, vložte verejný kľúč lokality a vyberte variant.

Joomla 4/5

Po inštalácii povoľte doplnok Systém – CallFlow (v Systém → Pluginy), prilepiť PUBLIC_SITE_KEY, wybierz wariant i podaj adres polityki prywatności.

Magento 2 / Adobe Commerce

Skopírujte modul do app/code/CallFlow/Callback, uruchom bin/magento setup:upgrade i skonfiguruj go w Obchody → Konfigurácia → Všeobecné → CallFlow. Modul obsahuje whitelist CSP pre skript a API samael.pl, więc nie musisz ręcznie modyfikować polityki bezpieczeństwa treści.

e107 2.3

Po inštalácii otvorte konfiguráciu CallFlow, vložte kľúč CF-…, wybierz wariant i włącz widget.

Strapi 4/5

Plugin poskytuje konfiguráciu verejných modulov /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

Balenie obsahuje zdrojový kód Rozšírenie aplikácie Theme (vloženie aplikácie pre plávajúcu miniaplikáciu a blok aplikácie s formulárom vloženým do sekcie) – toto nie je inštalátor obchodu. Nasadenie vyžaduje aplikáciu Shopify Partner a obchod pre vývojárov:

shopify app dev

shopify app deploy

Po inštalácii predajca aktivuje CallFlow Nastavenia témy → Vloženie aplikácie alebo pridá blok formulára do sekcie témy.

API pre vývojárov

CallFlow poskytuje REST API verziu 1.2.0 – tá istá zmluva poháňa mobilnú aplikáciu a verejné widgety.

Základy

• Základná adresa URL: https://callflowdesk.com/api/v1
• Autentifikácia: hlavička Authorization: Bearer <access_token> (JWT). Token uzyskasz przez POST /auth/login, a odświeżysz przez POST /auth/refresh z refresh_token.
• Žiadny token funguje iba: /auth/register, /auth/login, /auth/refresh oraz /public/leads.
• Chyby: formát odpovedí application/problem+json z polami type, title, status, code, detail, trace_id i (dla walidacji) errors.
• Stránkovanie: zoznamy sa vrátia next_cursor; kolejną stronę pobierzesz parametrem zapytania cursor.

Auth - Registrácia a životný cyklus relácie

Účet – hlavný účet, podúčty a štatistiky

Zdroje – webové stránky a balíky kontaktov

Potenciálni zákazníci - žiadosti o spätné volanie a ich stavy

Plán - plánovanie hovorov

Zariadenia - tlačné zariadenia

Verejné – koncové body pre widgety

Príklad: prihlásenie

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

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

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

Odpoveď 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"

Príklad: verejné odoslanie potenciálneho 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 znakov, napr. UUID): Opakovaný pokus o požiadavku s rovnakým kľúčom nevytvorí duplicitnú požiadavku.

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é polia: 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.

aplikácia pre Android

Aplikácia CallFlow je riadiacim centrom pre vaše hovory: sem chodia všetky správy z miniaplikácií, sem spravujete stránky, klávesy a kalendár spätných volaní. Aplikácia sa na Google Play objaví už čoskoro – dovtedy nájdete inštalačný balíček v sekcii Stiahnuť.

Kľúčové vlastnosti

• Poradie hovorov - nové požiadavky sú automaticky odoslané príslušnému projektu a zaradené do frontu podľa pracovného času a očakávaného času konverzácie; stavy (nové, prebiehajúce, spracované, zmeškané, spam) organizujú prácu.
• Rozvrh - kalendár spätného volania s automatickým plánovaním ďalšej dostupnej schôdzky jediným dotykom.
• Push upozornenia - každá nová správa okamžite spustí upozornenie; Zoznam zaregistrovaných zariadení spravujete v nastaveniach a stratenému telefónu môžete odvolať prístup.
• podúčty - ako vlastník účtu (hlavná rola) pozývate kolegov (vedľajšia rola) e-mailom a priraďujete im vybrané stránky; vidia iba zdroje a správy, ktoré sú im priradené.
• Export údajov - úplný export údajov účtu (stránky, prehľady, plán, súhlasy) do súboru JSON v súlade s GDPR.
• Odstránenie účtu - trvalé odstránenie účtu so všetkými údajmi priamo z aplikácie (vyžaduje potvrdenie hesla a pre účty Google - fráza "VYMAZAŤ ÚČET"); podrobnosti v sekcii Odstráňte svoj účet.

Riešenie problémov

Miniaplikácia sa vôbec nezobrazuje

Najčastejšou príčinou je neplatný kľúč. Skontrolujte atribút 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 správu „Neplatná konfigurácia“.

Kľúč je v správnom formáte, ale nie je aktívny. Stáva sa to vtedy, keď bol vygenerovaný nový kľúč (rotácia okamžite zruší platnosť starého) alebo keď bola stránka archivovaná. Prejdite na podrobnosti o webovej lokalite v aplikácii a skopírujte aktuálne kľúč a nahraďte ho v nastaveniach kódu alebo pluginu.

Formulár funguje, ale aplikácie sa do aplikácie nedostanú

Skontrolujte stav stránky v aplikácii: aplikácie prijímajú iba aktívne stránky. Pozastavená alebo archivovaná stránka neprijíma nových potenciálnych zákazníkov. Tiež skontrolujte, či si neprezeráte prehľady s filtrom stavu alebo v podúčte bez prístupu na túto stránku.

Miniaplikácia sa na WordPress s WooCommerce zobrazuje dvakrát

Máte aktívne oba doplnky: základný CallFlow a CallFlow pre WooCommerce. Od verzie 1.1.0 doplnok WooCommerce automaticky deaktivuje globálnu základnú miniaplikáciu – aktualizujte obe na 1.1.0. Ak problém pretrváva, zrušte začiarknutie políčka „Povoliť miniaplikáciu globálne“. Nastavenia → CallFlow. Pamätajte tiež na tento krátky kód [callflow] sam wyłącza widget globalny na danej podstronie.

Obchod s obmedzujúcim CSP blokuje miniaplikáciu

Ak vaša lokalita odosiela hlavičku Content-Security-Policy, pridajte 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 neposiela správy na localhost

Toto je zámerné: 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.

Ako zmeniť farby widgetu bez úpravy CSS stránky?

Použite atribúty Easy level priamo 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 Personalizáciaa hotové súpravy ukážková galéria.

Kde nájdem kľúč CF mojej stránky?

V aplikácii CallFlow otvorte "Packages and Pages", zvoľte strana - kláves 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ávam upozornenia push o nových prehľadoch

Skontrolujte, či má aplikácia povolenie na upozornenia v nastaveniach systému Android a či je vaše zariadenie v zozname zariadení v aplikácii a nebolo odvolané. Ak systém prepne aplikáciu do režimu spánku na pozadí, vypnite optimalizáciu batérie pre CallFlow.

Vygeneroval som nový kľúč a widget prestal fungovať

Rotácia kľúča okamžite zruší platnosť predchádzajúcej - ide o bezpečnostný prvok. Po vygenerovaní nového kľúča ho aktualizujte na všetkých miestach, kde je widget vložený: v kóde webovej stránky a v nastaveniach každého doplnku CMS.