Documentação

A documentação inclui widget 1.2.0, plug-ins CMS 1.1.0 e API versão 1.2.0. Última atualização: julho de 2026.

Início rápido

CallFlow é um widget de retorno de chamada gratuito com fila de chamadas automática. Um visitante do seu site deixa um número de telefone e a solicitação vai imediatamente para o aplicativo CallFlow do seu telefone. A inicialização leva alguns minutos e consiste em três etapas:

1. Crie uma conta - no aplicativo CallFlow para Android ou posterior painel web. A conta é gratuita.
2. Adicionar uma página - Na seção 'Pacotes e Páginas', adicione o endereço do seu site e copie a tecla curta começando com CF-. To publiczny klucz strony (PUBLIC_SITE_KEY) — pozwala wyłącznie wysyłać nowe zgłoszenia, nie daje dostępu do Twojego konta.
3. Cole o script - Coloque o seguinte código imediatamente antes da 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>

Isso é o suficiente. Um botão flutuante aparecerá no site e cada relatório acionará uma notificação push no aplicativo.

Widget HTML/JS

CallFlow 1.2.0 é um script de produção para páginas HTML regulares. Não requer uma estrutura ou bibliotecas externas. O formulário é executado em um Shadow DOM isolado - não interfere no CSS do seu site - e só pode enviar novas solicitações por meio da API pública do CallFlow.

Instalação Básica (Widget Flutuante)

Cole o script antes </body> — dokładnie tak jak w Início rápido. Variante padrão floating wyświetla pływający przycisk w rogu ekranu, który otwiera formularz.

Variante incorporada no conteúdo

Se você deseja colocar o formulário em um local específico da página (por exemplo, na subpágina de contato), adicione um container vazio e indique-o com o atributo 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>

Variantes disponíveis

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

Você pode assistir todas as variantes ao vivo no site Demonstração de widget.

Tabela completa de atributos de configuração

As configurações de urgência e política de privacidade também são recuperadas do CallFlow. O usuário do site não pode ativar um recurso que foi desativado pelo proprietário da conta.

Segurança e Privacidade

• não lê dados da conta ou lista de tickets;
• chave do site permite apenas que você crie um ticket;
• ocorre via HTTPS;
• o formulário contém um honeypot e requer consentimento explícito para contato; Formulário
• o widget não salva cookies e não utiliza armazenamento local;
• é normalizado e revalidado pela API;
• tem um tempo limite de 15 segundos e uma chave de idempotência para proteção contra duplicatas.

Personalização de aparência

A partir da versão 1.2.0, o widget herda a fonte do site por padrão (inherit, awaryjnie system-ui), a wygląd można dopasować na dwóch poziomach: Fácil (atributos simples) i Avançado (CSS de espectro completo). Atributos de personalização podem ser colocados na tag <script> ou no destino especificado por data-target (atrybut na elemencie docelowym ma pierwszeństwo). Bez tych atrybutów widget wygląda tak jak dotychczas.

Nível fácil - cores, dimensões, fonte

Cada atributo é opcional e mapeia para uma variável CSS definida no elemento host do widget (.callflow-widget-host):

Exemplo de correspondência do widget com o lado escuro com detalhes dourados:

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

As mesmas variáveis permeiam o Shadow DOM via herança CSS, então em vez de atributos você pode usar CSS de página puro (folha ou <style>):

#moj-kontener {

  --callflow-accent: #b8860b;

  --callflow-radius: 4px;

  --callflow-max-width: 460px;

}

Ordem de precedência: atributo data-* na elemencie docelowym → atrybut data-* na tagu <script> → zmienna CSS strony → starsze atrybuty data-*-color → wartości domyślne.

Nível avançado - espectro completo de CSS

::part() - Elementos importantes do formulário possuem atributos 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 bruto injetado no Shadow DOM após os estilos base (a cascata vence, afeta os seletores de widgets internos):

<div id="callback"

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

data-css-href - Endereço da planilha externa carregada no Shadow DOM. Por razões de segurança, apenas endereços são aceitos 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>

Ordem de estilo Shadow DOM: estilos base → folha z data-css-href → data-custom-css. Personalizacja jest w pełni opcjonalna i wstecznie kompatybilna — istniejące osadzenia działają bez zmian.

Eventos JavaScript

O widget emite eventos no elemento host e os propaga para o documento, para que você possa, por exemplo, enviar uma conversão para o sistema analítico após um relatório bem-sucedido:

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

  console.log(event.detail.receiptId);

});



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

  console.warn(event.detail.code);

});

Eventos disponíveis:

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

Plug-in WordPress

O plugin CallFlow 1.1.0 adiciona um widget a todo o seu site WordPress sem editar o modelo. Suporta variantes floating, box, sticky i compact oraz osadzanie formularza w treści przez shortcode.

Requisitos

• WordPress 6.0 ou posterior;
• PHP 7.4 ou posterior (testado em PHP 7.4 e 8.3);
• chave do site CF-… utworzony w aplikacji CallFlow.

Instalação passo a passo

1. Baixe o plugin - arquivo callflow-wordpress-1.1.0.zip znajdziesz w sekcji Baixar.
2. Instalar no painel do WordPress - vá para Plugins → Adicionar novo plugin → Carregar plugin no servidor, aponte para o arquivo ZIP baixado e clique Instalare após a instalação Habilitar.
3. Configurar - vá para Configurações → Fluxo de chamada e:
   • cole a chave na caixa PUBLIC_SITE_KEY (formato CF-XXXX-XXXX);
   • selecione Variante (padrão floating);
   • insira o endereço Política de Privacidade do seu site;
   • Habilite o widget globalmente e clique em Salvar alterações.

Incorporação no conteúdo (shortcode)

Para exibir um formulário dentro de uma postagem ou página, use o shortcode:

[callflow variant="box"]

Usar o shortcode desativa automaticamente o segundo widget global nesta subpágina - o formulário nunca será duplicado.

Problemas comuns

• Chave não salva - Plugin valida formato: chave deve começar com CF- i zawierać wyłącznie wielkie litery, cyfry i myślniki. Skopiuj go ponownie z aplikacji, bez spacji.
• O widget não aparece na página - campo de verificação Habilite o widget globalmente está verificado e a chave não está vazia. Se você usar um plugin de cache (por exemplo, LiteSpeed, WP Super Cache), limpe o cache após salvar suas configurações.
• O widget aparece duas vezes - você também tem o plugin CallFlow for WooCommerce ativo; veja a seção WooCommerce.

Plug-in WooCommerce

CallFlow for WooCommerce 1.1.0 é um plugin feito sob medida para lojas - ele usa a 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.

Requisitos

• WordPress 6.0 ou posterior, PHP 7.4 ou posterior (testado em PHP 7.4 e 8.3);
• plug-in ativo WooCommerce (obrigatório - sem ele o widget não será exibido);
• chave do site CF-… z aplikacji CallFlow.

Instalação passo a passo

1. Baixe o plugin - arquivo callflow-woocommerce-1.1.0.zip z sekcji Baixar.
2. Instalar — Plugins → Adicionar novo plugin → Carregar plugin no servidor, selecione ZIP, Instalar, Habilitar.
3. Configurar - vá para Configurações → CallFlow WooCommerce e:
   • colar PUBLIC_SITE_KEY;
   • selecione Variante: ecommerce (domyślny), floating lub sticky;
   • defina o seu próprio Configuração da página Cabeçalho (padrão "Você tem alguma dúvida sobre o produto?");
   • Habilite o widget da loja e salve.

Funciona com o plugin CallFlow básico

Ambos os plugins podem estar ativos ao mesmo tempo. Quando o widget WooCommerce está habilitado, ele desativa automaticamente o widget global do plugin subjacente, para que o formulário nunca seja exibido duas vezes. Se você deixar o campo-chave nas configurações do WooCommerce em branco, o plugin usará a chave do plugin CallFlow base.

Problemas comuns

• O widget não aparece - certifique-se de que o WooCommerce esteja instalado e ativo; o plugin exibe o widget apenas quando o WooCommerce está em execução.
• Dois widgets ao mesmo tempo - atualize ambos os plugins para a versão 1.1.0; versões mais antigas não coordenavam a visibilidade. Alternativamente, desmarque "Ativar widget globalmente" no plugin subjacente.
• Isto é beta - teste o plugin primeiro em uma cópia de teste da loja antes de habilitá-lo na produção.

Módulo PrestaShop 8

O módulo beta CallFlow 1.1.0 incorpora um widget de produção no rodapé da loja PrestaShop (hook displayFooter). Obsługuje warianty ecommerce, floating i sticky.

Requisitos

• PrestaShop 8.0 ou posterior;
• chave do site CF-… z aplikacji CallFlow;
• instale a versão beta primeiro na loja de teste.

Instalação passo a passo

1. Baixar módulo - arquivo callflow-prestashop8-1.1.0.zip z sekcji Baixar.
2. Instalar no painel - vá para Módulos → Gerenciador de Módulo → Carregar Módulo e aponte para o ZIP baixado. Você encontrará o módulo na categoria “Publicidade e marketing”.
3. Configurar - clique Configurar para o módulo CallFlow e:
   • colar PUBLIC_SITE_KEY;
   • selecione Variante: E-commerce (padrão), Flutuante ou Fixo;
   • conjunto Cabeçalho do widget (padrão "Tem alguma dúvida sobre este produto?" - insira a sua em polonês);
   • especifique endereço da política de privacidade loja; O script
   • definir interruptor Habilitado para "Sim" e clique Salvar.

Problemas comuns

• Erro "A chave CallFlow deve começar com CF-" - módulo valida o formato da chave; copie-o do aplicativo sem espaços.
• Widget não aparece após salvar - limpar cache de armazenamento (Avançado → Desempenho → Limpar cache) e verifique se a chave Ativado está definida como "Sim".
• O tema não invoca o rodapé - o widget está conectado ao gancho displayFooter; jeśli Twój motyw go nie renderuje, podepnij moduł do innego hooka w Aparência → Itens.

Outras plataformas

As integrações a seguir são versões beta técnicas da 1.1.0 - instale-as primeiro em seu ambiente de teste. Você encontrará todos os pacotes na seção Baixar.

Drupal 11/10

Após instalar o módulo, vá para Configuração → Serviços de Rede → CallFlow, cole a chave pública do site e selecione uma variante.

Joomla 4/5

Após a instalação, habilite o plugin Sistema - CallFlow (v Sistema → Plug-ins), cole PUBLIC_SITE_KEY, wybierz wariant i podaj adres polityki prywatności.

Magento 2/Adobe Commerce

Copiar módulo para app/code/CallFlow/Callback, uruchom bin/magento setup:upgrade i skonfiguruj go w Lojas → Configuração → Geral → CallFlow. O módulo contém uma lista de permissões CSP para o script e API samael.pl, więc nie musisz ręcznie modyfikować polityki bezpieczeństwa treści.

e107 2.3

Após a instalação, abra a configuração do CallFlow, cole a chave CF-…, wybierz wariant i włącz widget.

Correia 4/5

Plugin fornece configuração de pod público /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

O pacote inclui código fonte Extensão de aplicativo temático (aplicativo incorporado para um widget flutuante e bloco de aplicativo com um formulário incorporado na seção) - este não é um instalador de loja. A implantação requer o aplicativo Shopify Partner e a loja do desenvolvedor:

shopify app dev

shopify app deploy

Após a instalação, o vendedor ativa o CallFlow em Configurações do tema → Incorporações de aplicativos ou adiciona um bloco de formulário a uma seção de tema.

API para desenvolvedores

CallFlow fornece REST API versão 1.2.0 - o mesmo contrato alimenta o aplicativo móvel e os widgets públicos.

Noções básicas

• URL base: https://callflowdesk.com/api/v1
• Autenticação: cabeçalho O número Authorization: Bearer <access_token> (JWT). Token uzyskasz przez POST /auth/login, a odświeżysz przez POST /auth/refresh z refresh_token.
• Nenhum token só funciona: /auth/register, /auth/login, /auth/refresh oraz /public/leads.
• Erros: formato de respostas application/problem+json z polami type, title, status, code, detail, trace_id i (dla walidacji) errors.
• Paginação: lista o retorno next_cursor; kolejną stronę pobierzesz parametrem zapytania cursor.

Autenticação - Registro e ciclo de vida da sessão

Conta - Conta principal, subcontas e estatísticas

Fontes - Sites e pacotes de contato

Leads – solicitações de retorno de chamada e seus status

Agendamento - agendamento de chamadas

Dispositivos - dispositivos push

Público - terminais para widgets

Exemplo: login

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

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

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

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

Exemplo: envio público de um lead

Ponto final POST /public/leads nie wymaga tokenu — identyfikuje stronę po publicznym kluczu CF-…. Nagłówek Idempotency-Key jest obrigatório Marca (16-128 caracteres, por exemplo, UUID): Tentar novamente a solicitação com a mesma chave não criará uma solicitação duplicada.

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

  }'

Campos obrigatórios: 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.

Aplicativo Android

A aplicação CallFlow é o centro de comando para suas chamadas: é para onde vão todos os relatórios dos widgets, é para onde você gerencia páginas, chaves e o calendário de retorno de chamada. O aplicativo aparecerá no Google Play em breve – até então, você encontrará o pacote de instalação na seção Baixar.

Principais recursos

• Fila de chamadas - novas solicitações são enviadas automaticamente para o projeto apropriado e enfileiradas de acordo com o horário de trabalho e tempo de conversação esperado; status (novo, em andamento, processado, perdido, spam) organizam o trabalho.
• Cronograma - calendário de retorno de chamada com agendamento automático do próximo compromisso disponível com um toque.
• Notificações push - cada novo relatório aciona imediatamente uma notificação; Você gerencia a lista de dispositivos registrados nas configurações e pode revogar o acesso de um telefone perdido.
• Subcontas - como proprietário da conta (função principal), você convida colegas (subfunção) por e-mail e atribui-lhes páginas selecionadas; eles só veem fontes e relatórios atribuídos a eles.
• Exportação de dados - exportação completa dos dados da conta (páginas, relatórios, cronograma, consentimentos) para um arquivo JSON, de acordo com o GDPR.
• Exclusão de conta - exclusão permanente da conta com todos os dados diretamente do aplicativo (requer confirmação de senha, e para contas Google - a frase “EXCLUIR CONTA”); detalhes na seção Exclua sua conta.

Solução de problemas

O widget não aparece

A causa mais comum é uma chave inválida. Verifique o atributo 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 exibe mensagem "Configuração inválida"

A chave está no formato correto, mas não está ativa. Isso acontece quando uma nova chave é gerada (a rotação invalida a antiga imediatamente) ou a página é arquivada. Acesse os detalhes do site no aplicativo e copie atual e substitua-a em seu código ou configurações de plugin.

O formulário funciona, mas as inscrições não chegam ao aplicativo

Verifique o status do site na inscrição: apenas sites ativos aceitam inscrições. Uma página pausada ou arquivada não aceita novos leads. Verifique também se você não está visualizando relatórios com filtro de status ou em uma subconta sem acesso a esta página.

O widget aparece duas vezes no WordPress com WooCommerce

Você tem os dois plugins ativos: o CallFlow básico e o CallFlow para WooCommerce. A partir da versão 1.1.0, o plugin WooCommerce desabilita automaticamente o widget de base global – atualize ambos para 1.1.0. Se o problema persistir, desmarque "Ativar widget globalmente" em Configurações → Fluxo de chamada. Lembre-se também daquele shortcode [callflow] sam wyłącza widget globalny na danej podstronie.

Uma loja com um CSP restritivo bloqueia o widget

Se o seu site enviar um cabeçalho Content-Security-Policy, adicione um domínio 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.

O widget não envia relatórios no localhost

Isto é intencional: 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.

Como alterar as cores do widget sem editar o CSS da página?

Use atributos de nível Fácil diretamente na 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 Personalizaçãoe conjuntos prontos em galeria de demonstração.

Onde posso encontrar a chave CF do meu site?

Na aplicação CallFlow, abra "Pacotes e Páginas", selecione página - chave 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.

Não recebo notificações push sobre novos relatórios

Verifique se o aplicativo tem permissão para notificações nas configurações do Android e se o seu dispositivo está na lista de dispositivos do aplicativo e não foi revogado. Desative a otimização da bateria para CallFlow se o sistema colocar o aplicativo em suspensão em segundo plano.

Gerei uma nova chave e o widget parou de funcionar

A rotação de chaves invalida imediatamente a anterior - este é um recurso de segurança. Após gerar uma nova chave, atualize-a em todos os locais onde o widget está incorporado: no código do site e nas configurações de cada plugin CMS.