Principal Construindo Fluxos Como enviar variáveis para fluxos do Fluxo Controlado (sem perguntar de novo ao cliente)

Como enviar variáveis para fluxos do Fluxo Controlado (sem perguntar de novo ao cliente)

Última atualização em Oct 13, 2026

Quando usar

  • Você quer que o Fluxo Controlado aproveite dados que o cliente já deu na conversa com a ClaudIA, sem perguntar de novo

  • Você precisa entender quais variáveis padrão a ClaudIA envia automaticamente para o Fluxo Controlado (helpdeskId, channelType etc.)

  • Você quer ativar o extrator de variáveis para tornar a experiência mais fluida

  • Você precisa do telefone do cliente (ou de outro dado do contato) dentro de um fluxo ou de uma Tool

Pré-requisitos

  • Workspace do Fluxo Controlado criado e fluxo configurado

  • Seção interativa na ClaudIA configurada para acionar o fluxo

Sobre este artigo

O Fluxo Controlado tem dois mecanismos para receber dados antes mesmo de pedir ao cliente: as variáveis padrão (sempre enviadas pela ClaudIA) e o extrator de variáveis (que lê o histórico da conversa via LLM e preenche campos do fluxo). Este artigo cobre os dois — e explica como funciona o acionamento de um Fluxo Controlado pela ClaudIA.

Detalhes

Visão geral — campo Placeholder

O campo Placeholder dos cards Input permite que o Fluxo Controlado aproveite dados já informados pelo cliente na conversa com a ClaudIA, sem precisar perguntar de novo.

Basta descrever no Placeholder qual dado você quer capturar. Essa descrição funciona como um "prompt" para a ClaudIA procurar a informação no ticket/conversa e preencher a variável automaticamente.

Exemplo: se o Placeholder for "E-mail do usuário" e existir um e-mail no histórico, a ClaudIA o extrai (via LLM) e preenche a variável definida no fluxo. A response daquele Input não é disparada e a pergunta não se repete.

Variáveis padrão enviadas pela ClaudIA

Estas variáveis chegam automaticamente ao fluxo, sem nenhuma configuração adicional. Todas em formato texto (string). Algumas podem vir vazias, outras sempre têm valor.

Variável Descrição
helpdeskId Identificador do ticket no helpdesk de origem. Se o seu helpdesk é o próprio Cloud Chat, é o número da conversa no Cloud Chat. É a variável para consultar a conversa via API
cloudChatId Código único da conversa na ClaudIA. Sempre presente. Não use para consultar a conversa na API do seu helpdesk: para isso, use o helpdeskId
activeIntent Intenção (tópico) detectada na conversa atual. Se nenhuma for identificada, recebe DEFAULT
channelType Canal de origem: EMAIL WHATSAPP SMS CHAT FORM FACEBOOK INSTAGRAM NO_TYPE_PROVIDED
language Idioma detectado (pode ser nulo): pt-BR en es fr de it ja ko zh ru ar hi nl sv da fi pl tr
createdAt Data e hora de início da conversa
frustrationScore Nível de frustração calculado pela ClaudIA. 0 = sem frustração; valores maiores = maior insatisfação
abKey Chave de teste A/B (pode ser nula — nem toda conversa entra em A/B)
lastUserMessages Últimas mensagens enviadas pelo cliente desde a última resposta do agente
messages Histórico completo da conversa em formato texto

Formato do histórico de messages:

USER: olá
AGENT: Oi, eu sou a ClaudIA. Como posso te ajudar?
USER: então... queria saber como fazer [...]
AGENT: Entendi! Para fazer isso basta [...]

Para usar essas variáveis no fluxo, basta criar um card Condition:

Extrator de variáveis (do histórico)

Por padrão, os Fluxos Controlados pedem ao cliente todas as informações necessárias (número do pedido, e-mail etc.). Mas muitas vezes essas informações já foram dadas antes na conversa. Pedir de novo é UX ruim.

O extrator de variáveis analisa o histórico da conversa, coleta os dados necessários e os envia ao Fluxo Controlado no momento da ativação — eliminando perguntas redundantes.

Características:

  • Verifica o fluxo do Fluxo Controlado dinamicamente para saber quais variáveis precisam ser coletadas

  • A extração é feita pelo GPT via prompt definido no código da ClaudIA

  • Os dados coletados podem ser conferidos na auditoria do painel

Como configurar (dentro do Fluxo Controlado):

Para que uma variável seja extraída, é necessário:

  1. Bloco input com o placeholder preenchido, descrevendo a variável (ex: "Número do pedido no formato IN-XXXXXX")

  2. Condicional is set precedendo a variável, que verifica se ela já tem valor — assim você controla o que acontece se o extrator já preencheu

Acionamento do Fluxo Controlado pela ClaudIA

1 — Como o Fluxo Controlado é acionado

Um Fluxo Controlado é acionado pela ClaudIA via seção utilizada (detalhado em Como funciona a seção utilizada pela ClaudIA).

Passo a passo:

  1. Usuário envia uma mensagem

  2. ClaudIA analisa as responses das seções disponíveis

  3. ClaudIA aciona o Fluxo Controlado da seção com response mais adequada à mensagem do cliente

  4. Se duas seções de Fluxo Controlado forem selecionadas, prevalece a de maior score

2 — Como ocultar a response da seção interativa

Para que a response seja omitida, o Fluxo Controlado precisa ter acesso à primeira variável coletada no fluxo.

Exemplo: se a response contiver o texto "Qual o número do seu pedido?", a ClaudIA omitirá a pergunta caso o usuário já tenha informado o número do pedido. Para isso funcionar, é obrigatório preencher o Placeholder no card de coleta da variável.

A variável precisa existir no fluxo com o nome exato

As variáveis padrão só chegam ao fluxo se já existir uma variável com exatamente o mesmo nome dentro dele. O nome diferencia maiúsculas de minúsculas.

Duas formas de criar:

  1. Bloco Variáveis Nativas (mais simples): arraste o bloco, escolha o tipo na lista e o fluxo cria a variável com o nome correto sozinho. A lista cobre Helpdesk ID, Cloud Chat ID, Active Intent, Channel Type, Created At, Last User Messages e Messages.
  2. Manualmente: crie a variável digitando o nome idêntico. É o caminho para as que não estão no bloco, como idioma, score de frustração, chave de teste A/B e primeira mensagem do usuário.

Se a variável não existir no fluxo, o valor simplesmente não chega — sem erro e sem aviso. O sintoma é uma variável vazia no meio do fluxo.

O número do protocolo não é uma variável do fluxo

Esta é a confusão mais comum. Os identificadores que chegam ao fluxo são:

O que você quer Existe no fluxo? Como obter
Código único da conversa Sim Cloud Chat ID
Identificador do ticket no helpdesk de origem Sim Helpdesk ID
Número do protocolo exibido ao cliente Não Só nas mensagens do Cloud Chat, com a variável de protocolo

Se o objetivo é informar o protocolo ao cliente, faça isso por uma mensagem do Cloud Chat (automação, resposta rápida ou macro), não pelo fluxo. Veja o artigo sobre variáveis nas mensagens do Cloud Chat.

Fluxo Controlado e Tool não recebem as mesmas variáveis

O mesmo fluxo pode ser usado de duas maneiras, e o comportamento muda:

Fluxo Controlado acionado pela ClaudIA Tool usada por um Agente
Variáveis padrão da conversa Chegam automaticamente Só o helpdeskId, se declarado como parâmetro da Tool. As demais não chegam
Dados do cliente Extrator lê o histórico O Agente preenche os parâmetros
Onde os campos são definidos Blocos de input com Placeholder Bloco de declaração de variáveis

Helpdesk ID em Tool: declare um parâmetro chamado helpdeskId (também vale helpdesk_id) no bloco de declaração de variáveis da Tool. A ClaudIA preenche esse parâmetro automaticamente com o identificador do ticket, e o Agente nem chega a vê-lo.

As outras variáveis padrão (Cloud Chat ID, canal, idioma, mensagens etc.) não chegam à Tool. Se o fluxo depende de alguma delas, declare o dado como parâmetro da Tool e deixe explícito na descrição de onde o Agente deve tirá-lo.

O telefone do cliente não é uma variável do fluxo

Não existe variável padrão com o telefone (nem com o e-mail) do cliente. Há três formas de obter esse dado, da mais automática para a mais simples.

Opção 1 — Consultar a API do Cloud Chat (quando o seu helpdesk é o Cloud Chat)

  1. Garanta que o fluxo tenha a variável helpdeskId. Em Tool, declare o parâmetro helpdeskId, que é preenchido automaticamente
  2. Adicione um bloco HTTP Request com:
    • Método GET
    • URL https://{seu-cloud-chat}/api/v1/accounts/{id_da_sua_conta}/conversations/{{helpdeskId}}
    • Header api_access_token com o token de um usuário administrador. O token fica no perfil do usuário, em Token de acesso
  3. Salve o campo meta.sender.phone_number da resposta numa variável, por exemplo telefone
  4. Use essa variável no restante do fluxo ou na chamada da sua API

O telefone só vem preenchido quando o contato tem um número cadastrado. Em conversas de WhatsApp ele sempre existe. No widget do site, no e-mail, no Instagram e no Messenger ele geralmente vem vazio. Mantenha um caminho alternativo, como perguntar ao cliente.

Prefira o token de um usuário administrador ou de serviço, e não o de uma pessoa que pode sair da empresa. Se o token for revogado, a requisição para de funcionar.

Opção 2 — Enriquecimento de Contexto com Dados do contato

Ative o provedor Dados do contato no Enriquecimento de Contexto. O telefone cadastrado no contato passa a fazer parte do briefing que a ClaudIA lê antes da primeira resposta. Numa Tool, declare um parâmetro telefone e escreva na descrição que o Agente deve usar o telefone do contato informado no contexto da conversa.

Opção 3 — Pedir ao cliente

Use um bloco Input com o Placeholder preenchido, por exemplo "Telefone celular com DDD". Se o cliente já tiver informado o número na conversa, o extrator de variáveis preenche sozinho e a pergunta não se repete.

No Playground não há ticket real, então o helpdeskId não corresponde a uma conversa do Cloud Chat e o Enriquecimento de Contexto não roda. Teste as opções 1 e 2 numa conversa real.

Observações