Documentazione

La documentazione include il widget 1.2.0, i plugin CMS 1.1.0 e la versione API 1.2.0. Ultimo aggiornamento: luglio 2026.

Avvio rapido

CallFlow è un widget di richiamata gratuito con coda di chiamata automatica. Un visitatore del tuo sito web lascia un numero di telefono e la richiesta viene immediatamente inviata all'applicazione CallFlow sul tuo telefono. L’avvio richiede pochi minuti e si compone di tre passaggi:

1. Crea un account - nell'app CallFlow per Android o versioni successive pannello web. Il conto è gratuito.
2. Aggiungi una pagina - Nella sezione "Pacchetti e pagine", aggiungi l'indirizzo del tuo sito web e copia la chiave breve che inizia con CF-. To publiczny klucz strony (PUBLIC_SITE_KEY) — pozwala wyłącznie wysyłać nowe zgłoszenia, nie daje dostępu do Twojego konta.
3. Incolla lo script - Inserisci il seguente codice immediatamente prima del tag </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>

Basta. Sul sito Web verrà visualizzato un pulsante mobile e ogni rapporto attiverà una notifica push nell'app.

Widget HTML/JS

Il widget CallFlow 1.2.0 è uno script di produzione per normali pagine HTML. Non richiede un framework o librerie esterne. Il modulo viene eseguito in uno Shadow DOM isolato, non interferisce con il CSS del tuo sito e può inviare nuove richieste solo tramite l'API CallFlow pubblica.

Installazione di base (widget mobile)

Incolla lo script prima </body> — dokładnie tak jak w Avvio rapido. Variante predefinita floating wyświetla pływający przycisk w rogu ekranu, który otwiera formularz.

Variante incorporata nel contenuto

Se vuoi posizionare il form in un punto specifico della pagina (es. nella sottopagina contatti), aggiungi un contenitore vuoto e indicalo con l'attributo 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>

Varianti disponibili

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

Puoi guardare tutte le varianti dal vivo sul sito web Demo del widget.

Tabella degli attributi di configurazione completa

Le impostazioni relative all'urgenza e alla politica sulla privacy vengono inoltre recuperate da CallFlow. L'utente del sito web non può abilitare una funzionalità che è stata disabilitata dal proprietario dell'account.

Sicurezza e privacy

• non legge i dati dell'account o l'elenco dei ticket;
• ti consente solo di creare un ticket;
• avviene tramite HTTPS;
• il modulo contiene un honeypot e richiede il consenso esplicito per essere contattato; modulo
• il widget non salva cookie e non utilizza la memoria locale;
• è normalizzato e riconvalidato dall'API;
• ha un timeout di 15 secondi e una chiave di idempotenza per proteggerla dai duplicati.

Personalizzazione dell'aspetto

Dalla versione 1.2.0, il widget eredita per impostazione predefinita il carattere dal sito web (inherit, awaryjnie system-ui), a wygląd można dopasować na dwóch poziomach: Facile (attributi semplici) i Avanzato (CSS a spettro completo). Gli attributi di personalizzazione possono essere posizionati sul tag <script> o sulla destinazione specificata da data-target (atrybut na elemencie docelowym ma pierwszeństwo). Bez tych atrybutów widget wygląda tak jak dotychczas.

Livello facile: colori, dimensioni, carattere

Ogni attributo è facoltativo e viene mappato a una variabile CSS impostata sull'elemento host del widget (.callflow-widget-host):

Esempio di abbinamento del widget al lato scuro con accenti dorati:

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

Le stesse variabili permeano lo Shadow DOM tramite ereditarietà CSS, quindi invece degli attributi puoi usare il puro CSS della pagina (foglio o <style>):

#moj-kontener {

  --callflow-accent: #b8860b;

  --callflow-radius: 4px;

  --callflow-max-width: 460px;

}

Ordine di precedenza: attributo data-* na elemencie docelowym → atrybut data-* na tagu <script> → zmienna CSS strony → starsze atrybuty data-*-color → wartości domyślne.

Livello avanzato: spettro completo di CSS

::part() - Gli elementi importanti del modulo hanno attributi 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 - CSS grezzo inserito nello Shadow DOM dopo gli stili di base (la cascata vince, influisce sui selettori dei widget interni):

<div id="callback"

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

data-css-href - Indirizzo del foglio esterno caricato nello Shadow DOM. Per motivi di sicurezza si accettano solo indirizzi 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>

Ordine stile Shadow DOM: stili base → foglio z data-css-href → data-custom-css. Personalizacja jest w pełni opcjonalna i wstecznie kompatybilna — istniejące osadzenia działają bez zmian.

Eventi JavaScript

Il widget emette eventi sull'elemento host e li propaga al documento, così puoi, ad esempio, inviare una conversione al sistema di analisi dopo un report riuscito:

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

  console.log(event.detail.receiptId);

});



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

  console.warn(event.detail.code);

});

Eventi disponibili:

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

Plugin WordPress

Il plugin CallFlow 1.1.0 aggiunge un widget all'intero sito WordPress senza modificare il modello. Supporta varianti floating, box, sticky i compact oraz osadzanie formularza w treści przez shortcode.

Requisiti

• WordPress 6.0 o successivo;
• PHP 7.4 o successivo (testato su PHP 7.4 e 8.3);
• chiave del sito La chiave del sito CF-… utworzony w aplikacji CallFlow.

Installazione passo dopo passo

1. Scarica il plugin - file callflow-wordpress-1.1.0.zip znajdziesz w sekcji Scarica.
2. Installa nella dashboard di WordPress - vai a Plugin → Aggiungi nuovo plugin → Carica plugin sul server, punta al file ZIP scaricato, fai clic Installae dopo l'installazione Abilita.
3. Configura - vai a Impostazioni → Flusso chiamate e:
   • incolla la chiave nella casella CHIAVE_SITO_PUBBLICO (formato CF-XXXX-XXXX);
   • seleziona Variante (predefinito floating);
   • inserisci l'indirizzo Informativa sulla privacy del tuo sito;
   • Abilita il widget a livello globale e fare clic Salva modifiche.

Incorporamento nel contenuto (shortcode)

Per visualizzare un modulo all'interno di un post o di una pagina, utilizza lo shortcode:

[callflow variant="box"]

L'utilizzo dello shortcode disabilita automaticamente il secondo widget globale su questa sottopagina: il modulo non verrà mai duplicato.

Problemi comuni

• Chiave non salvata - il plugin convalida il formato: la chiave deve iniziare con CF- i zawierać wyłącznie wielkie litery, cyfry i myślniki. Skopiuj go ponownie z aplikacji, bez spacji.
• Il widget non viene visualizzato nella pagina - check field Abilita il widget a livello globale è selezionato e la chiave non è vuota. Se utilizzi un plug-in della cache (ad esempio LiteSpeed, WP Super Cache), svuota la cache dopo aver salvato le impostazioni.
• Il widget appare due volte - hai attivo anche il plugin CallFlow for WooCommerce; vedere la sezione WooCommerce.

Plug-in WooCommerce

CallFlow for WooCommerce 1.1.0 è un plugin su misura per i negozi: utilizza la variante 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.

Requisiti

• WordPress 6.0 o successivo, PHP 7.4 o successivo (testato su PHP 7.4 e 8.3);
• plugin attivo WooCommerce (richiesto - senza di esso il widget non verrà visualizzato);
• chiave del sito La chiave del sito CF-… z aplikacji CallFlow.

Installazione passo dopo passo

1. Scarica il plugin - file callflow-woocommerce-1.1.0.zip z sekcji Scarica.
2. Installa — Plugin → Aggiungi nuovo plugin → Carica plugin sul server, seleziona CAP, Installa, Abilita.
3. Configura - vai a Impostazioni → CallFlow WooCommerce e:
   • incolla CHIAVE_SITO_PUBBLICO;
   • seleziona Variante: ecommerce (domyślny), floating lub sticky;
   • imposta il tuo Intestazione (default "Hai una domanda sul prodotto?");
   • Abilita il widget del negozio e salva.

Funziona con il plugin CallFlow di base

Entrambi i plugin possono essere attivi contemporaneamente. Quando il widget WooCommerce è abilitato, disabilita automaticamente il widget globale del plugin sottostante, quindi il modulo non verrà mai visualizzato due volte. Se lasci vuoto il campo chiave nelle impostazioni di WooCommerce, il plug-in utilizzerà la chiave del plug-in CallFlow di base.

Problemi comuni

• Il widget non viene visualizzato - assicurati che WooCommerce sia installato e attivo; il plugin visualizza il widget solo quando WooCommerce è in esecuzione.
• Due widget contemporaneamente - aggiorna entrambi i plugin alla versione 1.1.0; older versions did not coordinate visibility. In alternativa, deseleziona "Abilita widget a livello globale" nel plug-in sottostante.
• Questa è la versione beta - Testare prima il plugin su una copia temporanea dello store prima di abilitarlo in produzione.

Modulo PrestaShop 8

Il modulo beta CallFlow 1.1.0 incorpora un widget di produzione nel footer del negozio PrestaShop (hook displayFooter). Obsługuje warianty ecommerce, floating i sticky.

Requisiti

• PrestaShop 8.0 o successivo;
• chiave del sito La chiave del sito CF-… z aplikacji CallFlow;
• installa prima la versione beta nell'archivio di staging.

Installazione passo dopo passo

1. Scarica il modulo - file callflow-prestashop8-1.1.0.zip z sekcji Scarica.
2. Installa sul pannello - vai a Moduli → Gestione moduli → Carica modulo e punta al ZIP scaricato. Troverai il modulo nella categoria "Pubblicità e marketing".
3. Configura - fare clic Configura per il modulo CallFlow e:
   • incolla CHIAVE_SITO_PUBBLICO;
   • seleziona Variante: E-commerce (predefinito), Floating o Sticky;
   • impostato Intestazione widget (predefinito "Hai una domanda su questo prodotto?" - inserisci la tua in polacco);
   • specificare indirizzo della privacy policy negozio; Lo script
   • imposta l'interruttore Abilitato su "Sì" e fare clic Intestazione Salva.

Problemi comuni

• Errore "La chiave CallFlow deve iniziare con CF-" - il modulo convalida il formato della chiave; copiatelo dall'applicazione senza spazi.
• Il widget non viene visualizzato dopo il salvataggio - clear store cache (Avanzate → Prestazioni → Svuota cache) e verificare che l'interruttore Abilitato sia impostato su "Sì".
• Il tema non richiama il piè di pagina - il widget è connesso all'hook displayFooter; jeśli Twój motyw go nie renderuje, podepnij moduł do innego hooka w Aspetto → Oggetti.

Altre piattaforme

Le seguenti integrazioni sono versioni beta tecniche della 1.1.0: installale prima nel tuo ambiente di staging. Troverai tutti i pacchetti nella sezione Scarica.

Drupal 10/11

Dopo aver installato il modulo, vai a Configurazione → Servizi di rete → CallFlow, incolla la chiave pubblica del sito e seleziona una variante.

Joomla 4/5

Dopo l'installazione, abilitare il plugin Sistema - Flusso di chiamata (v Sistema → Plugin), incolla PUBLIC_SITE_KEY, wybierz wariant i podaj adres polityki prywatności.

Magento 2 / Adobe Commerce

Copia modulo in app/code/CallFlow/Callback, uruchom bin/magento setup:upgrade i skonfiguruj go w Negozi → Configurazione → Generale → CallFlow. Il modulo contiene una whitelist CSP per lo script e l'API samael.pl, więc nie musisz ręcznie modyfikować polityki bezpieczeństwa treści.

e107 2.3

Dopo l'installazione, apri la configurazione di CallFlow, incolla la chiave CF-…, wybierz wariant i włącz widget.

Strapi 4/5

Il plugin fornisce la configurazione pubblica del 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

Il pacchetto include codice sorgente Estensione dell'app tema (incorporamento dell'app per un widget mobile e blocco dell'app con un modulo incorporato nella sezione): non è un programma di installazione del negozio. La distribuzione richiede l'app Shopify Partner e lo store per sviluppatori:

shopify app dev

shopify app deploy

Dopo l'installazione, il venditore attiva CallFlow in Impostazioni tema → Incorporamento app o aggiunge un blocco modulo a una sezione del tema.

API per sviluppatori

CallFlow fornisce la versione 1.2.0 dell'API REST: lo stesso contratto alimenta l'app mobile e i widget pubblici.

Nozioni di base

• URL di base: https://callflowdesk.com/api/v1
• Autenticazione: Il numero Authorization: Bearer <access_token> (JWT). Token uzyskasz przez POST /auth/login, a odświeżysz przez POST /auth/refresh z refresh_token.
• Nessun token funziona solo: /auth/register, /auth/login, /auth/refresh oraz /public/leads.
• Errori: formato risposte application/problem+json z polami type, title, status, code, detail, trace_id i (dla walidacji) errors.
• Impaginazione: elenca il ritorno next_cursor; kolejną stronę pobierzesz parametrem zapytania cursor.

Autenticazione: registrazione e ciclo di vita della sessione

Conto - Conto principale, conti secondari e statistiche

Fonti - Siti web e pacchetti di contatti

Lead: richieste di richiamata e relativi stati

Pianificazione - pianificazione delle chiamate

Dispositivi - dispositivi push

Pubblico: endpoint per i widget

Esempio: login

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

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

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

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

Esempio: invio pubblico di un lead

Punto finale POST /public/leads nie wymaga tokenu — identyfikuje stronę po publicznym kluczu CF-…. Nagłówek Idempotency-Key jest richiesto (16-128 caratteri, ad esempio UUID): riprovare la richiesta con la stessa chiave non creerà una richiesta duplicata.

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

  }'

Campi obbligatori: 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.

Applicazione Android

L'applicazione CallFlow è il centro di comando delle tue chiamate: tutti i report dei widget vanno qui, tu gestisci le pagine, i tasti e il calendario delle richiamate. L'applicazione apparirà presto su Google Play: fino ad allora troverai il pacchetto di installazione nella sezione Scarica.

Caratteristiche principali

• Coda di chiamate - le nuove richieste vengono automaticamente inviate al progetto appropriato e messe in coda in base all'orario di lavoro e al tempo di conversazione previsto; gli stati (nuovo, in corso, gestito, mancato, spam) organizzano il lavoro.
• Pianificazione - Calendario di richiamata con pianificazione automatica del prossimo appuntamento disponibile con un solo tocco.
• Notifiche push - ogni nuova segnalazione attiva immediatamente una notifica; Gestisci l'elenco dei dispositivi registrati nelle impostazioni e puoi revocare l'accesso per un telefono smarrito.
• Sottoconti - come proprietario dell'account (ruolo principale), inviti i colleghi (ruolo secondario) tramite e-mail e assegni loro le pagine selezionate; vedono solo le fonti e i rapporti loro assegnati.
• Esportazione dati - esportazione completa dei dati dell'account (pagine, report, pianificazione, consensi) in un file JSON, in conformità con GDPR.
• Eliminazione dell'account - cancellazione permanente dell'account con tutti i dati direttamente dall'applicazione (richiede la conferma della password e per gli account Google - la frase "CANCELLA ACCOUNT"); dettagli nella sezione Elimina il tuo account.

Risoluzione dei problemi

Il widget non viene visualizzato affatto

La causa più comune è una chiave non valida. Controlla l'attributo 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.

Il widget visualizza il messaggio "Configurazione non valida".

La chiave è nel formato corretto ma non è attiva. Ciò accade quando è stata generata una nuova chiave (la rotazione invalida immediatamente quella vecchia) oppure la pagina è stata archiviata. Vai ai dettagli del sito web nell'applicazione e copia corrente e sostituiscila nel codice o nelle impostazioni del plugin.

Il modulo funziona, ma le domande non arrivano alla domanda

Controlla lo stato del sito nell'applicazione: solo i siti attivi accettano iscrizioni. Una pagina in pausa o archiviata non accetta nuovi lead. Controlla inoltre di non visualizzare i report con un filtro di stato o su un account secondario senza accesso a questa pagina.

Il widget appare due volte su WordPress con WooCommerce

Hai entrambi i plugin attivi: CallFlow base e CallFlow per WooCommerce. A partire dalla versione 1.1.0, il plugin WooCommerce disabilita automaticamente il widget di base globale: aggiorna entrambi alla 1.1.0. Se il problema persiste, deseleziona "Abilita widget a livello globale" in Impostazioni → Flusso chiamate. Ricorda anche quello shortcode [callflow] sam wyłącza widget globalny na danej podstronie.

Un negozio con un CSP restrittivo blocca il widget

Se il tuo sito invia un'intestazione Content-Security-Policy, aggiungi un dominio 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.

Il widget non invia report su localhost

Questo è intenzionale: campo 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.

Come cambiare i colori del widget senza modificare il CSS della pagina?

Utilizza gli attributi del livello Easy direttamente sul tag <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 Personalizzazionee set già pronti galleria dimostrativa.

Dove posso trovare la chiave CF del mio sito?

Nell'applicazione CallFlow, aprire "Pacchetti e pagine", selezionare pagina - chiave 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.

Non ricevo notifiche push sui nuovi report

Verifica che l'app disponga dell'autorizzazione per le notifiche nelle impostazioni di Android e che il tuo dispositivo sia nell'elenco dei dispositivi nell'app e non sia stato revocato. Disattiva l'ottimizzazione della batteria per CallFlow se il sistema mette l'applicazione in modalità di sospensione in background.

Ho generato una nuova chiave e il widget ha smesso di funzionare

La rotazione della chiave invalida immediatamente quella precedente: questa è una funzionalità di sicurezza. Dopo aver generato una nuova chiave, aggiornala in tutti i luoghi in cui è incorporato il widget: nel codice del sito web e nelle impostazioni di ciascun plugin CMS.