Dokumentacja

Dokumentacja obejmuje widget 1.2.0, wtyczki CMS 1.1.0 oraz API w wersji 1.2.0. Ostatnia aktualizacja: lipiec 2026.

Szybki start

CallFlow to darmowy widget callback z automatyczną kolejką rozmów. Odwiedzający Twoją stronę zostawia numer telefonu, a zgłoszenie natychmiast trafia do aplikacji CallFlow na Twoim telefonie. Uruchomienie zajmuje kilka minut i składa się z trzech kroków:

1. Załóż konto — w aplikacji CallFlow na Androida lub w panelu www. Konto jest bezpłatne.
2. Dodaj stronę — w sekcji „Pakiety i Strony” dodaj adres swojej witryny i skopiuj krótki klucz zaczynający się od CF-. To publiczny klucz strony (PUBLIC_SITE_KEY) — pozwala wyłącznie wysyłać nowe zgłoszenia, nie daje dostępu do Twojego konta.
3. Wklej skrypt — umieść poniższy kod bezpośrednio przed znacznikiem </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 wystarczy. Na stronie pojawi się pływający przycisk, a każde zgłoszenie wywoła powiadomienie push w aplikacji.

Widget HTML/JS

Widget CallFlow 1.2.0 to produkcyjny skrypt dla zwykłych stron HTML. Nie wymaga frameworka ani zewnętrznych bibliotek. Formularz działa w izolowanym Shadow DOM — nie koliduje z CSS-em Twojej strony — i może wyłącznie wysyłać nowe zgłoszenia przez publiczne API CallFlow.

Instalacja podstawowa (widget pływający)

Wklej skrypt przed </body> — dokładnie tak jak w Szybkim starcie. Domyślny wariant floating wyświetla pływający przycisk w rogu ekranu, który otwiera formularz.

Wariant osadzony w treści

Jeśli chcesz umieścić formularz w konkretnym miejscu strony (np. na podstronie kontaktu), dodaj pusty kontener i wskaż go atrybutem 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>

Dostępne warianty

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

Wszystkie warianty możesz obejrzeć na żywo na stronie Demo widgetu.

Pełna tabela atrybutów konfiguracyjnych

Ustawienia pilności i polityki prywatności są dodatkowo pobierane z CallFlow. Użytkownik strony nie może włączyć funkcji wyłączonej przez właściciela konta.

Bezpieczeństwo i prywatność

• skrypt nie odczytuje danych konta ani listy zgłoszeń;
• klucz strony pozwala wyłącznie utworzyć zgłoszenie;
• transmisja odbywa się przez HTTPS;
• formularz zawiera honeypot i wymaga wyraźnej zgody na kontakt;
• widget nie zapisuje cookies i nie korzysta z local storage;
• numer jest normalizowany i ponownie walidowany przez API;
• żądanie ma timeout 15 sekund i klucz idempotencji chroniący przed duplikatem.

Personalizacja wyglądu

Od wersji 1.2.0 widget domyślnie dziedziczy font ze strony (inherit, awaryjnie system-ui), a wygląd można dopasować na dwóch poziomach: Easy (proste atrybuty) i Advanced (pełne spektrum CSS). Atrybuty personalizacji można umieścić na tagu <script> lub na elemencie docelowym wskazanym przez data-target (atrybut na elemencie docelowym ma pierwszeństwo). Bez tych atrybutów widget wygląda tak jak dotychczas.

Poziom Easy — kolory, wymiary, font

Każdy atrybut jest opcjonalny i mapowany na zmienną CSS ustawianą na elemencie hosta widgetu (.callflow-widget-host):

Przykład dopasowania widgetu do ciemnej strony ze złotymi akcentami:

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

Te same zmienne przenikają do Shadow DOM przez dziedziczenie CSS, więc zamiast atrybutów możesz użyć czystego CSS strony (arkusz lub <style>):

#moj-kontener {

  --callflow-accent: #b8860b;

  --callflow-radius: 4px;

  --callflow-max-width: 460px;

}

Kolejność pierwszeństwa: atrybut data-* na elemencie docelowym → atrybut data-* na tagu <script> → zmienna CSS strony → starsze atrybuty data-*-color → wartości domyślne.

Poziom Advanced — pełne spektrum CSS

::part() — istotne elementy formularza mają atrybuty 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 — surowy CSS wstrzykiwany do Shadow DOM po stylach bazowych (wygrywa kaskadą, działa na wewnętrzne selektory widgetu):

<div id="callback"

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

data-css-href — adres zewnętrznego arkusza ładowanego do Shadow DOM. Ze względów bezpieczeństwa akceptowane są wyłącznie 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>

Kolejność stylów w Shadow DOM: style bazowe → arkusz z data-css-href → data-custom-css. Personalizacja jest w pełni opcjonalna i wstecznie kompatybilna — istniejące osadzenia działają bez zmian.

Zdarzenia JavaScript

Widget emituje zdarzenia na elemencie hosta i propaguje je do dokumentu, dzięki czemu możesz np. wysłać konwersję do systemu analitycznego po udanym zgłoszeniu:

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

  console.log(event.detail.receiptId);

});



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

  console.warn(event.detail.code);

});

Dostępne zdarzenia:

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

Wtyczka WordPress

Wtyczka CallFlow 1.1.0 dodaje widget do całej witryny WordPress bez edycji szablonu. Obsługuje warianty floating, box, sticky i compact oraz osadzanie formularza w treści przez shortcode.

Wymagania

• WordPress 6.0 lub nowszy;
• PHP 7.4 lub nowszy (testowano na PHP 7.4 i 8.3);
• klucz strony CF-… utworzony w aplikacji CallFlow.

Instalacja krok po kroku

1. Pobierz wtyczkę — plik callflow-wordpress-1.1.0.zip znajdziesz w sekcji Pobierz.
2. Zainstaluj w panelu WordPress — przejdź do Wtyczki → Dodaj nową wtyczkę → Wyślij wtyczkę na serwer, wskaż pobrany plik ZIP, kliknij Zainstaluj, a po instalacji Włącz.
3. Skonfiguruj — przejdź do Ustawienia → CallFlow i:
   • wklej klucz w polu PUBLIC_SITE_KEY (format CF-XXXX-XXXX);
   • wybierz Wariant (domyślnie floating);
   • podaj adres Polityki prywatności Twojej witryny;
   • zaznacz Włącz widget globalnie i kliknij Zapisz zmiany.

Osadzenie w treści (shortcode)

Aby wyświetlić formularz wewnątrz wpisu lub strony, użyj shortcode’u:

[callflow variant="box"]

Użycie shortcode’u automatycznie wyłącza drugi, globalny widget na tej podstronie — formularz nigdy się nie zdubluje.

Typowe problemy

• Klucz nie zapisuje się — wtyczka waliduje format: klucz musi zaczynać się od CF- i zawierać wyłącznie wielkie litery, cyfry i myślniki. Skopiuj go ponownie z aplikacji, bez spacji.
• Widget nie pojawia się na stronie — sprawdź, czy pole Włącz widget globalnie jest zaznaczone i czy klucz nie jest pusty. Jeśli używasz wtyczki cache (np. LiteSpeed, WP Super Cache), wyczyść pamięć podręczną po zapisaniu ustawień.
• Widget pojawia się dwa razy — masz jednocześnie aktywną wtyczkę CallFlow for WooCommerce; zobacz sekcję WooCommerce.

Wtyczka WooCommerce

CallFlow for WooCommerce 1.1.0 to wtyczka dopasowana do sklepów — domyślnie używa wariantu 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.

Wymagania

• WordPress 6.0 lub nowszy, PHP 7.4 lub nowszy (testowano na PHP 7.4 i 8.3);
• aktywna wtyczka WooCommerce (wymagana — bez niej widget się nie wyświetli);
• klucz strony CF-… z aplikacji CallFlow.

Instalacja krok po kroku

1. Pobierz wtyczkę — plik callflow-woocommerce-1.1.0.zip z sekcji Pobierz.
2. Zainstaluj — Wtyczki → Dodaj nową wtyczkę → Wyślij wtyczkę na serwer, wybierz ZIP, Zainstaluj, Włącz.
3. Skonfiguruj — przejdź do Ustawienia → CallFlow WooCommerce i:
   • wklej PUBLIC_SITE_KEY;
   • wybierz Wariant: ecommerce (domyślny), floating lub sticky;
   • ustaw własny Nagłówek formularza (domyślnie „Masz pytanie o produkt?”);
   • zaznacz Włącz widget w sklepie i zapisz.

Współpraca z bazową wtyczką CallFlow

Obie wtyczki można mieć aktywne jednocześnie. Gdy widget WooCommerce jest włączony, automatycznie wyłącza globalny widget bazowej wtyczki, więc formularz nigdy nie wyświetli się podwójnie. Jeśli pole klucza w ustawieniach WooCommerce zostawisz puste, wtyczka użyje klucza z bazowej wtyczki CallFlow.

Typowe problemy

• Widget nie pojawia się — upewnij się, że WooCommerce jest zainstalowany i aktywny; wtyczka wyświetla widget tylko przy działającym WooCommerce.
• Dwa widgety naraz — zaktualizuj obie wtyczki do wersji 1.1.0; starsze wersje nie koordynowały widoczności. Alternatywnie odznacz „Włącz widget globalnie” w bazowej wtyczce.
• To beta — przetestuj wtyczkę najpierw na kopii stagingowej sklepu, zanim włączysz ją na produkcji.

Moduł PrestaShop 8

Moduł CallFlow 1.1.0 beta osadza produkcyjny widget w stopce sklepu PrestaShop (hook displayFooter). Obsługuje warianty ecommerce, floating i sticky.

Wymagania

• PrestaShop 8.0 lub nowszy;
• klucz strony CF-… z aplikacji CallFlow;
• wersję beta zainstaluj najpierw na sklepie stagingowym.

Instalacja krok po kroku

1. Pobierz moduł — plik callflow-prestashop8-1.1.0.zip z sekcji Pobierz.
2. Zainstaluj w panelu — przejdź do Moduły → Menedżer modułów → Załaduj moduł i wskaż pobrany ZIP. Moduł znajdziesz w kategorii „Reklama i marketing”.
3. Skonfiguruj — kliknij Konfiguruj przy module CallFlow i:
   • wklej PUBLIC_SITE_KEY;
   • wybierz Wariant: E-commerce (domyślny), Floating lub Sticky;
   • ustaw Nagłówek widgetu (domyślnie „Have a question about this product?” — wpisz własny po polsku);
   • podaj adres polityki prywatności sklepu;
   • ustaw przełącznik Enabled na „Yes” i kliknij Save.

Typowe problemy

• Błąd „The CallFlow key must start with CF-” — moduł waliduje format klucza; skopiuj go z aplikacji bez spacji.
• Widget nie pojawia się po zapisaniu — wyczyść cache sklepu (Zaawansowane → Wydajność → Wyczyść cache) i sprawdź, czy przełącznik Enabled jest ustawiony na „Yes”.
• Motyw nie wywołuje stopki — widget jest podpięty do hooka displayFooter; jeśli Twój motyw go nie renderuje, podepnij moduł do innego hooka w Wygląd → Pozycje.

Inne platformy

Poniższe integracje są wersjami beta technicznymi 1.1.0 — zainstaluj je najpierw na środowisku stagingowym. Wszystkie paczki znajdziesz w sekcji Pobierz.

Drupal 10/11

Po instalacji modułu przejdź do Konfiguracja → Usługi sieciowe → CallFlow, wklej publiczny klucz strony i wybierz wariant.

Joomla 4/5

Po instalacji włącz plugin System - CallFlow (w System → Pluginy), wklej PUBLIC_SITE_KEY, wybierz wariant i podaj adres polityki prywatności.

Magento 2 / Adobe Commerce

Skopiuj moduł do app/code/CallFlow/Callback, uruchom bin/magento setup:upgrade i skonfiguruj go w Stores → Configuration → General → CallFlow. Moduł zawiera whitelistę CSP dla skryptu oraz API samael.pl, więc nie musisz ręcznie modyfikować polityki bezpieczeństwa treści.

e107 2.3

Po instalacji otwórz konfigurację CallFlow, wklej klucz CF-…, wybierz wariant i włącz widget.

Strapi 4/5

Plugin udostępnia publiczną konfigurację pod /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

Paczka zawiera kod źródłowy rozszerzenia Theme App Extension (app embed dla widgetu pływającego oraz app block z formularzem osadzonym w sekcji) — to nie jest instalator sklepu. Wdrożenie wymaga aplikacji Shopify Partner i sklepu developerskiego:

shopify app dev

shopify app deploy

Po instalacji sprzedawca aktywuje CallFlow w Theme settings → App embeds albo dodaje blok formularza do sekcji motywu.

API dla programistów

CallFlow udostępnia REST API w wersji 1.2.0 — ten sam kontrakt obsługuje aplikację mobilną i publiczne widgety.

Podstawy

• Bazowy URL: https://callflowdesk.com/api/v1
• Uwierzytelnianie: nagłówek Authorization: Bearer <access_token> (JWT). Token uzyskasz przez POST /auth/login, a odświeżysz przez POST /auth/refresh z refresh_token.
• Bez tokenu działają wyłącznie: /auth/register, /auth/login, /auth/refresh oraz /public/leads.
• Błędy: odpowiedzi w formacie application/problem+json z polami type, title, status, code, detail, trace_id i (dla walidacji) errors.
• Paginacja: listy zwracają next_cursor; kolejną stronę pobierzesz parametrem zapytania cursor.

Auth — rejestracja i cykl życia sesji

Account — konto Main, Subkonta i statystyki

Sources — strony internetowe i pakiety kontaktowe

Leads — zgłoszenia callback i ich statusy

Schedule — planowanie rozmów

Devices — urządzenia push

Public — endpointy dla widgetów

Przykład: logowanie

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

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

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

Odpowiedź 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"

Przykład: publiczne wysłanie leada

Endpoint POST /public/leads nie wymaga tokenu — identyfikuje stronę po publicznym kluczu CF-…. Nagłówek Idempotency-Key jest wymagany (16–128 znaków, np. UUID): ponowienie żądania z tym samym kluczem nie utworzy duplikatu zgłoszenia.

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

  }'

Pola wymagane: 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.

Aplikacja Android

Aplikacja CallFlow to centrum dowodzenia Twoimi rozmowami: tu trafiają wszystkie zgłoszenia z widgetów, tu zarządzasz stronami, kluczami i kalendarzem oddzwonień. Aplikacja pojawi się wkrótce w Google Play — do tego czasu paczkę instalacyjną znajdziesz w sekcji Pobierz.

Najważniejsze funkcje

• Kolejka rozmów — nowe zgłoszenia automatycznie trafiają do właściwego projektu i ustawiają się w kolejce według godzin pracy i zakładanego czasu rozmowy; statusy (nowe, w trakcie, obsłużone, nieodebrane, spam) porządkują pracę.
• Harmonogram — kalendarz oddzwonień z automatycznym planowaniem najbliższego wolnego terminu jednym dotknięciem.
• Powiadomienia push — każde nowe zgłoszenie natychmiast wywołuje powiadomienie; listą zarejestrowanych urządzeń zarządzasz w ustawieniach i możesz odwołać dostęp zgubionego telefonu.
• Subkonta — jako właściciel konta (rola main) zapraszasz e-mailem współpracowników (rola sub) i przydzielasz im wybrane strony; widzą wyłącznie przypisane im źródła i zgłoszenia.
• Eksport danych — pełny eksport danych konta (strony, zgłoszenia, harmonogram, zgody) do pliku JSON, zgodnie z RODO.
• Usunięcie konta — trwałe usunięcie konta wraz ze wszystkimi danymi bezpośrednio z aplikacji (wymaga potwierdzenia hasłem, a dla kont Google — frazą „USUN KONTO”); szczegóły w sekcji Usuń konto.

Rozwiązywanie problemów

Widget w ogóle się nie pokazuje

Najczęstsza przyczyna to błędny klucz. Sprawdź atrybut 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 wyświetla komunikat „Nieprawidłowa konfiguracja”

Klucz ma poprawny format, ale nie jest aktywny. Dzieje się tak, gdy wygenerowano nowy klucz (rotacja unieważnia stary natychmiast) albo strona została zarchiwizowana. Wejdź w aplikacji w szczegóły strony, skopiuj aktualny klucz i podmień go w kodzie lub w ustawieniach wtyczki.

Formularz działa, ale zgłoszenia nie docierają do aplikacji

Sprawdź status strony w aplikacji: zgłoszenia przyjmują tylko strony aktywne. Strona wstrzymana (paused) lub zarchiwizowana nie przyjmuje nowych leadów. Sprawdź też, czy nie przeglądasz zgłoszeń z filtrem statusu lub na subkoncie bez dostępu do tej strony.

Widget pojawia się dwa razy na WordPressie z WooCommerce

Masz aktywne obie wtyczki: bazową CallFlow i CallFlow for WooCommerce. Od wersji 1.1.0 wtyczka WooCommerce automatycznie wyłącza globalny widget bazowej — zaktualizuj obie do 1.1.0. Jeśli problem zostaje, odznacz „Włącz widget globalnie” w Ustawienia → CallFlow. Pamiętaj też, że shortcode [callflow] sam wyłącza widget globalny na danej podstronie.

Sklep z restrykcyjnym CSP blokuje widget

Jeśli Twoja strona wysyła nagłówek Content-Security-Policy, dodaj domenę 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.

Na localhost widget nie wysyła zgłoszeń

To celowe: 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 zmienić kolory widgetu bez edycji CSS strony?

Użyj atrybutów poziomu Easy bezpośrednio na tagu <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 Personalizacja, a gotowe zestawy w galerii demo.

Gdzie znajdę klucz CF- mojej strony?

W aplikacji CallFlow otwórz „Pakiety i Strony”, wybierz stronę — klucz 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.

Nie dostaję powiadomień push o nowych zgłoszeniach

Sprawdź, czy aplikacja ma zgodę na powiadomienia w ustawieniach Androida oraz czy Twoje urządzenie jest na liście urządzeń w aplikacji i nie zostało odwołane. Wyłącz optymalizację baterii dla CallFlow, jeśli system usypia aplikację w tle.

Wygenerowałem nowy klucz i widget przestał działać

Rotacja klucza natychmiast unieważnia poprzedni — to funkcja bezpieczeństwa. Po wygenerowaniu nowego klucza zaktualizuj go we wszystkich miejscach, gdzie widget jest osadzony: w kodzie strony i w ustawieniach każdej wtyczki CMS.