​

Construindo Fluxos

​

Visão geral

ZappFlux Editor
└── Canvas (drag-and-drop workspace)
    ├── Blocks (Bubbles, Inputs, Logic, Integrations)
    │   └── Connected via arrows to define flow direction
    ├── Variables (store and reuse data throughout the flow)
    ├── Groups (organize blocks into logical sections)
    └── Publish (make the flow live to end users)

• Chatbots com tecnologia de IA para WhatsApp, Web, Instagram e muito mais
• Formulários de captura de leads com ramificação condicional
• Sistemas de triagem de suporte ao cliente com transferência humana
• Fluxos de trabalho de reserva e agendamento de consultas
• Assistentes de comércio eletrônico com cobrança de pagamentos
• Sequências de integração e pesquisas interativas

​

Começando

​

Criando um novo fluxo

1. Navigate to Dashboard → Tools → ZappFlux → Flows
2. Click New Flow (or the + button)
3. Give your flow a name
4. Choose a starting template or start from blank
5. The flow editor opens automatically

​

Navegação na tela

• Pan: Clique e arraste no espaço vazio da tela
• Zoom: roda de rolagem ou gesto de pinça (trackpad)
• Selecionar bloco: clique em um bloco
• Mover Bloco: Clique e arraste um bloco para reposicionar
• Conectar blocos: arraste da alça de saída (lado direito) de um bloco para a alça de entrada (lado esquerdo) de outro
• Excluir conexão: Clique na seta entre os blocos e pressione Excluir

​

Tipos de bloco

​

💬 Bolhas — Envio de conteúdo aos usuários

​

Texto

• Conteúdo da mensagem (suporta formatação Markdown)
• Interpolação variável usando {{variable_name}}
• Atraso de digitação opcional (simula tempo de resposta realista)

"Hello, {{user_name}}! Welcome to our support chat. 👋"

​

Imagem

• Fonte da imagem: faça upload de um arquivo (PNG, JPG, GIF, WebP) ou insira um URL público
• Texto alternativo para acessibilidade
• Legenda opcional abaixo da imagem

​

Vídeo

• Fontes suportadas: YouTube, Vimeo ou URL direto do arquivo de vídeo
• Opção de reprodução automática
• Título/legenda do vídeo

​

Áudio

• Fonte de áudio: carregue um arquivo (MP3, WAV, OGG) ou insira um URL
• Exibido como um widget de reprodutor de áudio padrão

​

Incorporar

• URL to embed (must support iframe embedding)
• Dimensions (width and height)
• Útil para incorporar calendários, mapas ou páginas de produtos

​

📥 Entradas — Coletando informações dos usuários

​

Entrada de texto

• Texto de espaço reservado mostrado no campo de entrada
• Variável para armazenar a resposta
• Limite de caracteres opcional
• Etiqueta do botão (“Enviar”, “Enviar” ou texto personalizado)

​

Número

• Restrições de valor mínimo e máximo
• Mensagem de erro mostrada se a validação falhar
• Variável para armazenar a resposta

​

E-mail

• Validação de formato de e-mail integrada (rejeita entradas malformadas)
• Mensagem de erro personalizada para entrada inválida
• Variável para armazenar a resposta

​

Telefone

• Seletor de código de país (opcional — pode ser bloqueado para um país específico)
• Validação de formato
• Variável para armazenar a resposta

​

Data/Hora

• Modo: somente data, somente hora ou data + hora
• Restrições de data mínima e máxima
• Variável para armazenar o valor selecionado

​

Botões

• Até 10 opções de botões
• Cada botão possui um rótulo e um valor opcional (pode ser diferente do rótulo de exibição)
• Modo de escolha múltipla vs. única
• Variável para armazenar a(s) opção(ões) selecionada(s)

• Mantenha os rótulos dos botões curtos (menos de 40 caracteres) para renderização consistente em todos os canais
• Use botões em vez de entradas de texto livre sempre que possível para melhorar a qualidade dos dados e reduzir respostas ambíguas

​

Escolha de imagem

• Cada opção possui uma imagem (upload ou URL) e um rótulo
• Seleção única ou múltipla
• Variável para armazenar a(s) seleção(ões)

​

Carregamento de arquivo

• Tipos de arquivos aceitos (PDF, imagens, documentos, etc.)
• Limite máximo de tamanho de arquivo
• Variável para armazenar a URL do arquivo enviado

​

Pagamento

• Stripe — Cartões de crédito/débito, Apple Pay, Google Pay
• PayPal — saldo do PayPal, contas bancárias vinculadas, cartões

• Valor (fixo ou retirado de uma variável)
• Moeda
• Nome/descrição do item
• Variável para armazenar o status do pagamento e ID da transação

​

Avaliação

• Tipo de classificação: Estrelas (1–5) ou Número (1–10)
• Etiqueta opcional por valor de classificação
• Variável para armazenar a classificação

​

⚡ Lógica — Controlando o comportamento do fluxo

​

Definir variável

• Nome da variável a ser definida
• Valor: um valor estático, outra variável ou uma expressão JavaScript

• Inicializando variáveis de contador (set count = 0)
• Formatação de valores (set full_name = "{{first_name}} {{last_name}}")
• Armazenar carimbos de data/hora ou valores calculados

​

Doença

• Lado esquerdo: uma variável
• Operador: igual, diferente, contém, maior que, menor que, está vazio, não está vazio
• Lado direito: um valor ou outra variável
• Múltiplas condições podem ser encadeadas com AND/OR

IF {{plan_type}} equals "Pro"
    → Show Pro features path
ELSE
    → Show upgrade prompt path

​

Redirecionar

• URL de destino (estático ou criado a partir de variáveis)
• Abrir em: mesma aba ou nova aba
• Atraso opcional antes do redirecionamento

​

Roteiro

• Bloco de código JavaScript personalizado
• Acesso a todas as variáveis de fluxo via variables.variable_name
• Pode definir variáveis usando setVariable('variable_name', value)

• Formatação ou análise de string complexa
• Cálculos matemáticos além de expressões simples
• Manipulação e formatação de datas
• Chamando APIs do navegador (para fluxos da web)

​

Espere

• Duração: segundos, minutos ou horas
• Mensagem opcional exibida ao usuário durante a espera

​

Pular

• Destino: um ID de bloco específico dentro do fluxo atual ou um outro fluxo inteiro

• Voltando a um menu após a conclusão de um caminho
• Vincular a um subfluxo reutilizável (por exemplo, um fluxo de perguntas frequentes compartilhado)
• Criação de loops circulares para lógica de nova tentativa

​

Webhook

• Método: GET, POST, PUT, PATCH, DELETE
• URL: endpoint para chamar (suporta interpolação variável)
• Cabeçalhos: pares de valores-chave (por exemplo, Autorização, Tipo de conteúdo)
• Corpo: carga útil JSON (para métodos POST/PUT/PATCH)
• Mapeamento de resposta: extraia valores da resposta e armazene-os em variáveis

• Envio de dados de leads para um CRM (HubSpot, Salesforce)
• Procurando dados do usuário em seu próprio banco de dados
• Acionamento de um pedido em uma plataforma de e-commerce
• Publicação de dados em um webhook Zapier ou Make

​

Link de fluxo (subfluxo)

• Selecione o fluxo de destino em um menu suspenso
• Mapeamento de variáveis: passe variáveis do fluxo atual para o subfluxo
• Após a conclusão do subfluxo, a execução retorna para o próximo bloco no fluxo pai

​

🔌 Integrações — Conectores Nativos

​

OpenAI (ChatGPT)

• Seleção de modelo (GPT-5.4, GPT-5.4 Mini, GPT-4o, etc.)
• Prompt do sistema (defina a personalidade e as restrições da IA)
• Mensagem do usuário: a entrada a ser enviada ao modelo (geralmente uma variável contendo a última mensagem do usuário)
• Variável de resposta: onde a resposta da IA é armazenada
• Avançado: temperatura, máximo de tokens, modo de histórico de conversas

• Passe {{user_message}} para OpenAI e exiba a resposta em um balão de texto
• Use um prompt do sistema para restringir a IA a um domínio específico (por exemplo, “Você é um agente de atendimento ao cliente da Acme Corp. Responda apenas a perguntas sobre nossos produtos.”)
• Ative o modo de histórico de conversas para manter o contexto em várias trocas

​

Planilhas Google

• Ação: Inserir linha, Atualizar linha, Obter linha ou Obter todas as linhas
• Seleção de planilha e planilha (da sua conta do Google conectada)
• Mapeamento de colunas: mapeie variáveis de fluxo para colunas da planilha

• Nome do evento
• Parâmetros personalizados (pares de valores-chave, suporta variáveis)

• flow_started — quando um usuário inicia o fluxo
• lead_captured — quando as informações de contato são coletadas
• payment_completed — quando um pagamento bem-sucedido é feito
• human_requested — quando um usuário solicita um agente humano

​

Zapier / Make

• URL do Webhook (do seu cenário Zap ou Make)
• Carga útil de dados: selecione quais variáveis enviar

​

Bate-papo

• URL da API Chatwoot e token de acesso
• Caixa de entrada para atribuir a conversa
• Atribuição de agente (opcional)
• Atributos personalizados para passar para Chatwoot

​

Enviar e-mail

• Do nome e endereço de e-mail
• Para endereçar (suporta variáveis)
• Linha de assunto (suporta variáveis)
• Corpo: HTML ou texto simples (suporta variáveis)
• Provedor: credenciais SMTP ou SendGrid configuradas em Configurações de fluxo

​

Ações ZappWay

• Atualizar as variáveis do contato atual
• Atribuir uma conversa a um agente específico
• Adicionar ou remover tags de um contato
• Acione uma notificação na caixa de entrada do ZappWay

​

Variáveis

​

Usando variáveis ​​em texto

"Hi {{user_name}}, your order #{{order_id}} has been confirmed!"

​

Tipos de variáveis

​

Variáveis ​​​​do sistema

​

Ramificação de fluxo e lógica condicional

​

Ramificação Simples (Botões)

[Button Block: "What do you need help with?"]
├── "Track my order" → [Order tracking path]
├── "Return a product" → [Returns path]
└── "Speak to a human" → [Chatwoot handoff]

​

Filial Baseada em Condição

[Set Variable: plan = {{selected_plan}}]
[Condition: IF plan equals "Enterprise"]
├── YES → [Enterprise onboarding path]
└── NO  → [Standard onboarding path]

​

Condições aninhadas

[Condition: IF score >= 8]
├── YES → [Promoter path (NPS)]
└── NO  → [Condition: IF score >= 5]
           ├── YES → [Passive path]
           └── NO  → [Detractor path]

​

Publicando um fluxo

1. Termine de editar seu fluxo
2. Clique em Publicar no canto superior direito do editor
3. Confirme a caixa de diálogo se solicitado
4. Seu fluxo agora está ativo em seu URL público

​

Modo de visualização

1. Click the Preview button (play icon) in the toolbar
2. A live preview of the flow opens in a side panel or new tab
3. Interact with the flow exactly as an end user would
4. All blocks execute normally in preview, including integrations

​

Melhores práticas

​

Solução de problemas

​

Problema: o fluxo não responde à entrada do usuário

• Mensagens são enviadas mas o fluxo não avança
• O bloco de entrada parece estar preso

1. Verifique se o bloco de entrada tem uma variável atribuída – blocos sem uma variável de destino podem não salvar as respostas corretamente
2. Verifique se a saída do bloco está conectada ao próximo bloco
3. Visualize o fluxo e verifique se há erros no console do navegador
4. Certifique-se de que o canal esteja conectado corretamente em Configurações → Canais
5. Republicar o fluxo após fazer as correções

​

Problema: o bloco de condição não ramifica corretamente

• O fluxo sempre segue o mesmo ramo, independentemente do valor da variável
• Comportamento inesperado na lógica condicional

1. Use o bloco Script antes da condição para registrar o valor da variável: console.log(variables.your_variable)
2. Verifique a distinção entre maiúsculas e minúsculas — “Pro” não é igual a “pro” em uma comparação de igualdade exata; use letras minúsculas consistentemente
3. Verifique se a variável está realmente sendo definida antes da execução do bloco de condição
4. Verifique se há espaços em branco à esquerda ou à direita no valor da variável - use o bloco Script para cortá-lo: setVariable('plan', variables.plan.trim())

​

Problema: o bloco Webhook retorna um erro

• O bloco Webhook mostra um indicador de erro vermelho
• Os dados de integração não estão sendo enviados ou recebidos

1. Clique no bloco Webhook para visualizar a resposta no painel de propriedades – verifique o código de status HTTP e a mensagem de erro
2. Verifique se o URL está correto e acessível na Internet
3. Verifique se os cabeçalhos necessários (por exemplo, Authorization: Bearer your_token) estão incluídos
4. Valide a estrutura do corpo JSON usando uma ferramenta como JSONLint
5. Teste o endpoint do webhook de forma independente usando Postman ou curl antes de adicioná-lo ao fluxo

​

Problema: Bloco OpenAI não gera respostas

• O bloco AI parece travar ou retorna respostas vazias
• Erro “Chave de API inválida” no bloco

1. Verifique se a chave da API OpenAI está salva corretamente em Configurações de fluxo → Integrações → OpenAI
2. Verifique se há problemas de cobrança em sua conta OpenAI – uma cota esgotada faz com que todas as chamadas de API falhem
3. Certifique-se de que o modelo selecionado no bloco esteja disponível em seu plano OpenAI
4. Verifique se a variável de entrada da mensagem do usuário não está vazia quando o bloco é executado

​

Apoiar

• E-mail: support@zappway.ai
• Incluir: nome do fluxo, capturas de tela dos blocos em questão e uma descrição do comportamento esperado versus real

• Qual tipo de bloco está causando o problema
• O canal que você está testando
• Se o problema ocorre no modo de visualização, ao vivo ou em ambos
• Quaisquer mensagens de erro mostradas no bloco ou no console do navegador

• API ZappFlux completa e referência de bloco: docs.zappflux.zappway.ai