> For the complete documentation index, see [llms.txt](https://help.hyperflow.global/docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://help.hyperflow.global/docs/builder-hyperflow/gerenciamento-de-aplicativos/fluxos/acao/variavel-de-usuario-externa.md).

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

{% hint style="warning" %}
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.
{% endhint %}

***

### 🧭 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.

<figure><img src="https://3829578295-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FRWteFkm020DS5IbXoSgj%2Fuploads%2FyqSRrRS8vzy6rqkzNGCS%2Fimage.png?alt=media&amp;token=17e8a269-dc91-4d7c-84eb-cfd04995c5df" alt=""><figcaption><p>Imagem 1 - Painel de módulos com a categoria Ação expandida e o módulo Variável de Usuário Externo visível</p></figcaption></figure>

***

### 🔍 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**.

<figure><img src="https://3829578295-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FRWteFkm020DS5IbXoSgj%2Fuploads%2FyoWx7YUGZahin81VXUKw%2Fimage.png?alt=media&amp;token=fe7c404b-9dbe-4d90-b3c0-6af540c36602" alt=""><figcaption><p>Imagem 2 - Painel de configuração do módulo Variável de Usuário Externo aberto, na aba Operação</p></figcaption></figure>

***

#### 🎯 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}}`). |

{% hint style="info" %}
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.
{% endhint %}

***

#### 🧩 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.

{% hint style="info" %}
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.
{% endhint %}

***

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

<figure><img src="https://3829578295-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FRWteFkm020DS5IbXoSgj%2Fuploads%2F7lHix3WVojL63qXcybye%2Fimage.png?alt=media&amp;token=5c99e512-d1e0-44d3-a82c-74354e280ac7" alt=""><figcaption><p>Imagem 3 - Opção de 'Tags' selecionada com amostragem dos métodos existentes.</p></figcaption></figure>

{% hint style="warning" %}
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**.
{% endhint %}

***

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

<figure><img src="https://3829578295-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FRWteFkm020DS5IbXoSgj%2Fuploads%2FHOFyqzV9MHMVe9FsUum0%2Fimage.png?alt=media&amp;token=c5c115da-a582-4ef3-b333-110f8a1ff1ef" alt=""><figcaption><p>Imagem 4 - Operação Ler dados selecionada, com o aviso sobre {{input.user}} visível</p></figcaption></figure>

***

#### 🧾 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.

<figure><img src="https://3829578295-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FRWteFkm020DS5IbXoSgj%2Fuploads%2F3oclGjfoA8Caw0GtNrv7%2Fimage.png?alt=media&amp;token=45939cfb-829f-40af-9dd4-51bf318ba755" alt=""><figcaption><p>Imagem 5 - Aba 'Editar JSON' exibida.</p></figcaption></figure>

{% hint style="info" %}
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**'.
{% endhint %}

***

#### 🔀 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**.