Variável de usuário externa

O módulo Variável de Usuário Externo opera as informações de um contato diferente do que está conversando com o bot no momento. Com ele, o fluxo pode salvar variáveis, aplicar etiquetas ou ler dados de qualquer outro contato da plataforma, sem precisar que esse contato esteja participando da conversa atual.

Gravar variáveis ou etiquetas neste módulo cria o contato informado, caso ele ainda não exista na plataforma. Já a leitura de dados só funciona se o contato já existir: se ele não existir, a leitura não encontra nada.

---

🧭 Como acessar

1. No menu lateral, clique em Gerenciamento de aplicativos.

2. Em seguida, clique em Fluxos.

3. Abra ou crie um fluxo e acesse a área de trabalho do fluxo.

4. No painel de módulos, localize a categoria Ação (identificada pela cor vermelha).

5. Arraste o módulo Variável de Usuário Externo para a área de trabalho do fluxo.

Imagem 1 - Painel de módulos com a categoria Ação expandida e o módulo Variável de Usuário Externo visível

---

🔍 Conhecendo o módulo

Ao clicar duas vezes no módulo na área de trabalho do fluxo, um painel de configuração é aberto na lateral da tela, com duas abas: Operação e Editor JSON.

Imagem 2 - Painel de configuração do módulo Variável de Usuário Externo aberto, na aba Operação

---

🎯 Contato alvo

Antes de escolher o que fazer, defina de qual contato este módulo vai ler ou gravar informações.

Campo	O que preencher
Informar o tipo de canal manualmente	Chave desligada (padrão): escolha o tipo de canal em uma lista. Chave ligada: informe uma variável do fluxo que já contenha o tipo de canal, em vez de escolher na lista.
Tipo de canal	O canal ao qual o contato pertence (WhatsApp, e-mail, entre outros). Aparece como lista ou como campo de variável, dependendo da chave acima.
Contato	O identificador do contato dentro desse canal: o número de telefone no WhatsApp, o endereço no e-mail, e assim por diante. Pode ser um valor fixo ou uma variável do fluxo (ex.: {{flow.phone}}).

O contato é identificado pela combinação de canal e identificador, não por um número de WhatsApp específico do seu aplicativo: qualquer número de WhatsApp do mesmo aplicativo encontra o mesmo contato, já que o identificador é o telefone da pessoa.

---

🧩 Operação

Escolha o que este módulo vai fazer com o contato indicado acima:

• Definir variáveis: cria ou sobrescreve variáveis salvas nesse outro contato.

• Tags: adiciona, remove, sobrescreve ou verifica as etiquetas desse outro contato.

• Ler dados: lê as informações já salvas desse outro contato, sem alterar nada.

---

1️⃣ Definir variáveis

🎯 Propósito

Salvar ou atualizar informações vinculadas ao contato indicado em Contato alvo, da mesma forma que o módulo Variável de Usuário faz para o contato da conversa atual.

✅ Como fazer na tela

1. Com Definir variáveis selecionado, uma tabela Variáveis aparece, com as colunas Variável e Valor.

2. Clique em + para adicionar uma nova linha, e informe o nome e o valor da informação que quer salvar. Pode ser texto, número, verdadeiro/falso, ou uma variável do fluxo.

3. Repita para cada informação que quiser salvar nesse outro contato.

4. Para remover uma variável já salva, desmarque a caixinha ao lado dela ou apague a linha.

📌 Resultado esperado

Quando o fluxo executar esse módulo, os valores informados são salvos no contato indicado em Contato alvo (que é criado automaticamente se ainda não existir). Variáveis desmarcadas ou apagadas são removidas desse contato.

Use valores em formato de lista ou objeto quando precisar salvar informações mais complexas, como uma lista de itens. Um texto simples é salvo exatamente como digitado.

---

2️⃣ Tags

🎯 Propósito

Adicionar, remover, sobrescrever ou verificar etiquetas do contato indicado em Contato alvo.

✅ Como fazer na tela

1. Com Tags selecionado, escolha a Ação:

   • Adicionar: inclui as etiquetas informadas, mantendo as que já existiam nesse contato.

   • Remover: retira as etiquetas informadas, mantendo as demais.

   • Sobrescrever: substitui todas as etiquetas desse contato pelas informadas aqui (deixar em branco remove todas as etiquetas do contato).

   • Verificar se contém: não altera nada, apenas confere se o contato já tem alguma das etiquetas informadas.

2. No campo de etiquetas, informe uma ou mais etiquetas.

📌 Resultado esperado

• Nas ações Adicionar, Remover e Sobrescrever, as etiquetas do contato indicado são atualizadas, e a execução segue pela saída Sucesso.

• Na ação Verificar se contém, a execução segue pela saída Sucesso quando o contato já tem pelo menos uma das etiquetas informadas, e pela saída Erro quando não tem nenhuma.

Imagem 3 - Opção de 'Tags' selecionada com amostragem dos métodos existentes.

A ação Verificar se contém é a única, dentro dessa operação, que não cria o contato quando ele não existe: se o contato indicado em Contato alvo não existir, a execução segue direto pela saída Erro.

---

3️⃣ Ler dados

🎯 Propósito

Consultar as informações já salvas do contato indicado em Contato alvo, sem alterar nada nele, para usá-las em outro ponto do fluxo.

✅ Como fazer na tela

1. Selecione a operação Ler dados. Nenhum campo adicional aparece: a leitura usa apenas o que foi definido em Contato alvo.

📌 Resultado esperado

Se o contato existir, os dados dele ficam disponíveis para o próximo módulo do fluxo através de {{input.user}}, e a execução segue pela saída Sucesso. Se o contato não existir, a execução segue pela saída Erro.

Imagem 4 - Operação Ler dados selecionada, com o aviso sobre {{input.user}} visível

---

🧾 Editor JSON

Nesta aba, disponível apenas quando a operação é Definir variáveis, você define as mesmas variáveis em formato JSON. As duas abas ficam sempre sincronizadas: o que você edita em uma aparece automaticamente na outra.

Imagem 5 - Aba 'Editar JSON' exibida.

Uma chave excluída no Editor JSON também é removida do contato, exatamente como excluir a linha correspondente na aba Operação. Uma outra observação importante é: Essa aba de 'Editor JSON' só é exibida se a opção de operação for 'Definir variáveis'.

---

🔀 Saídas do módulo

O módulo tem duas saídas:

• Sucesso: a operação foi concluída. Na operação Ler dados, os dados do contato ficam disponíveis através de {{input.user}}.

• Erro: a operação não pôde ser concluída. Isso acontece quando o canal ou o contato não são informados, quando o contato não existe na operação Ler dados, ou quando o contato não existe e a ação de Tags escolhida é Verificar se contém.

---

💡 Caso de uso

Cenário: depois que um cliente faz uma compra e informa o telefone de um amigo para receber um cupom de indicação, a empresa quer verificar se esse amigo já é um contato conhecido e, se não for, já salvar o cupom para ele.

Configuração:

1. Adicione o módulo Variável de Usuário Externo no ponto do fluxo em que o telefone do amigo é informado.

2. Em Contato alvo, selecione o tipo de canal WhatsApp e informe o telefone recebido no campo Contato (ex.: {{flow.telefone_amigo}}).

3. Na Operação, selecione Definir variáveis e crie a variável cupom_indicacao com o valor do cupom gerado.

4. Conecte a saída Sucesso para a continuidade do fluxo.

Resultado: o cupom fica salvo no contato do amigo, mesmo que ele nunca tenha conversado com o bot antes. Quando ele iniciar uma conversa depois, o fluxo pode consultar {{user.cupom_indicacao}} normalmente.

---

📌 Dicas úteis

• Use este módulo quando o fluxo precisar salvar, etiquetar ou consultar informações de um contato diferente de quem está conversando com o bot no momento.

• Para gravar ou ler variáveis do próprio contato da conversa atual, use o módulo Variável de Usuário no lugar.

• Lembre-se de que Definir variáveis e as ações de Tags (exceto Verificar se contém) criam o contato automaticamente, caso ele ainda não exista.

• A operação Ler dados e a ação Verificar se contém não criam o contato: se ele não existir, a execução segue pela saída Erro.

• Sempre conecte a saída Erro a um caminho adequado do fluxo, já que este módulo pode falhar (por exemplo, ao ler dados de um contato que não existe).

---

📝 Resumo

• O módulo Variável de Usuário Externo opera variáveis, etiquetas e dados de um contato diferente do que está na conversa atual.

• O contato é definido pelo tipo de canal e pelo identificador dele (telefone, e-mail, etc.), na seção Contato alvo.

• Três operações disponíveis: Definir variáveis, Tags (adicionar, remover, sobrescrever ou verificar se contém) e Ler dados.

• Gravar variáveis ou etiquetas cria o contato quando ele não existe; ler dados ou verificar etiquetas exige que o contato já exista.

• Os dados lidos com Ler dados ficam disponíveis para o próximo módulo através de {{input.user}}.

• O módulo tem uma saída de Sucesso e uma de Erro.